1 package com.atlassian.vcache;
2
3 import com.atlassian.annotations.PublicApi;
4
5 import java.util.Arrays;
6 import java.util.Map;
7 import java.util.Optional;
8 import java.util.concurrent.CompletionStage;
9 import java.util.function.Supplier;
10
11 /**
12 * Represents an {@link ExternalCache} where all operations are performed directly on the external cache system.
13 * See the {@link ExternalCache} documentation for more information.
14 *
15 * @param <V> the value type
16 * @since 1.0
17 */
18 @PublicApi
19 public interface DirectExternalCache<V>
20 extends ExternalCache<V>, ExternalWriteOperationsUnbuffered<V> {
21 /**
22 * Returns an identified value that is associated with a specified key. The {@link IdentifiedValue#identifier()}
23 * may be used in subsequent CAS operations, such as
24 * {@link #removeIf(String, CasIdentifier)} and
25 * {@link #replaceIf(String, CasIdentifier, Object)}.
26 *
27 * @param key the key to check.
28 * @return an {@link Optional} which may contain the identified value associated with the key.
29 */
30 CompletionStage<Optional<IdentifiedValue<V>>> getIdentified(String key);
31
32 /**
33 * Returns an identified value that is associated with a specified key. The {@link IdentifiedValue#identifier()}
34 * may be used in subsequent CAS operations, such as
35 * {@link #removeIf(String, CasIdentifier)} and
36 * {@link #replaceIf(String, CasIdentifier, Object)}.
37 *
38 * @param key the key to check.
39 * @param supplier used to generate the value, if one does not exist already for the key. The supplier may not
40 * return {@code null}.
41 * @return an {@link Optional} which may contain the identified value associated with the key.
42 */
43 CompletionStage<IdentifiedValue<V>> getIdentified(String key, Supplier<V> supplier);
44
45 /**
46 * Returns the {@link IdentifiedValue}'s that are associated with the specified keys. It is equivalent to calling
47 * {@link #getBulkIdentified(Iterable)} passing {@code Arrays.asList(keys)} as the parameter.
48 *
49 * @param keys the keys to check.
50 * @return A {@link Map} that is keyed on the {@code keys} specified. Each entry in the {@link Map} will have
51 * {@link Optional} which may contain the {@link IdentifiedValue} associated with the key.
52 */
53 @SuppressWarnings("unchecked")
54 default CompletionStage<Map<String, Optional<IdentifiedValue<V>>>> getBulkIdentified(String... keys) {
55 return getBulkIdentified(Arrays.asList(keys));
56 }
57
58 /**
59 * Returns the {@link IdentifiedValue}'s that are associated with the specified keys.
60 *
61 * @param keys the keys to check.
62 * @return A {@link Map} that is keyed on the {@code keys} specified. Each entry in the {@link Map} will have
63 * {@link Optional} which may contain the {@link IdentifiedValue} associated with the key.
64 */
65 CompletionStage<Map<String, Optional<IdentifiedValue<V>>>> getBulkIdentified(Iterable<String> keys);
66
67 /**
68 * Removes the specified entry, iff the specified CAS identifier matches.
69 *
70 * @param key the key of the entry to remove
71 * @param casId the CAS identifier to match
72 * @return whether the entry was removed
73 */
74 CompletionStage<Boolean> removeIf(String key, CasIdentifier casId);
75
76 /**
77 * Replaces the value for a specified entry, iff the specified CAS identifier matches.
78 *
79 * @param key the key of the entry to replace it's value
80 * @param casId the CAS identifier to match
81 * @param newValue the new value to replace with
82 * @return whether the value was replaced
83 */
84 CompletionStage<Boolean> replaceIf(String key, CasIdentifier casId, V newValue);
85 }