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 net.jcip.annotations.ThreadSafe;
20
21 import java.util.concurrent.Callable;
22 import java.util.concurrent.ExecutionException;
23
24 /**
25 * This will allow you to submit an operation, encapsulated by a {@link Callable}, and keyed by an
26 * Object <K>, such that the result of the Callable will be available to any concurrent callers with
27 * the same Object key. The result of the Callable is discarded after the operation has succeeded.
28 * <p>
29 * There is an assumption that the callers that are using this will submit the same Operations
30 * associated with the same keyed Object AND that the operations will be idempotent. This structure
31 * only ensures that if Concurrent operations with the same key are submitted that ONLY ONE of the
32 * operations will be executed. If the operations are not concurrent then both operations will be
33 * executed, hence the need for them to be idempotent.
34 * <p>
35 * Essentially, this is a Map whose elements expire very quickly. It is particularly useful for
36 * situations where you need to get or create the result, and you want to prevent concurrent
37 * creation of the result.
38 */
39 @ThreadSafe public interface ConcurrentOperationMap<K, R> {
40 /**
41 * The operation <R> will be keyed on the name <K>.
42 *
43 * @param key the key, like any map key this should be an immutable object that correctly
44 * implements {@link #hashCode()} and {@link #equals(Object)}
45 * @param operation is the operation to execute whose result will be accessible to any
46 * concurrent callers with the same key.
47 * @return result of the operation
48 * @throws ExecutionException if the callable generated a checked exception, otherwise a runtime
49 * exception or error will be thrown
50 */
51 R runOperation(K key, Callable<R> operation) throws ExecutionException;
52 }