1 /**
2 * Copyright 2008 Atlassian Pty Ltd
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.atlassian.util.concurrent;
18
19 import java.util.concurrent.Callable;
20 import java.util.concurrent.ExecutionException;
21
22 import net.jcip.annotations.ThreadSafe;
23
24 /**
25 * This will allow you to submit an operation, encapsulated by a
26 * {@link Callable}, and keyed by an Object <K>, such that the result of the
27 * Callable will be available to any concurrent callers with the same Object
28 * key. The result of the Callable is discarded after the operation has
29 * succeeded.
30 * <p>
31 * There is an assumption that the callers that are using this will submit the
32 * same Operations associated with the same keyed Object AND that the operations
33 * will be idempotent. This structure only ensures that if Concurrent operations
34 * with the same key are submitted that ONLY ONE of the operations will be
35 * executed. If the operations are not concurrent then both operations will be
36 * executed, hence the need for them to be idempotent.
37 * <p>
38 * Essentially, this is a Map whose elements expire very quickly. It is
39 * particularly useful for situations where you need to get or create the
40 * result, and you want to prevent concurrent creation of the result.
41 */
42 @ThreadSafe
43 public interface ConcurrentOperationMap<K, R> {
44 /**
45 * The operation <R> will be keyed on the name <K>.
46 *
47 * @param key the key, like any map key this should be an immutable object
48 * that correctly implements {@link Object#hashCode()} and
49 * {@link Object#equals(Object)}
50 * @param operation is the operation to execute whose result will be
51 * accessible to any concurrent callers with the same key.
52 * @return result of the operation
53 * @throws ExecutionException if the callable generated a checked exception,
54 * otherwise a runtime exception or error will be thrown
55 */
56 R runOperation(K key, Callable<R> operation) throws ExecutionException;
57 }