1 package com.atlassian.vcache;
2
3 import javax.annotation.Nonnull;
4
5 import com.atlassian.annotations.PublicApi;
6
7 /**
8 * Represents the factory for creating caches.
9 *
10 * <p>
11 * Notes:
12 * </p>
13 * <ul>
14 * <li>
15 * {@link JvmCache}'s and {@link RequestCache}'s are identified by their name and cache type. I.e. A
16 * {@link JvmCache} called <tt>'Williams'</tt> and a {@link RequestCache} called <tt>'Williams'</tt> are
17 * considered to be separate caches.
18 * </li>
19 * <li>
20 * {@link ExternalCache}'s are identified by their name and cache type.
21 * </li>
22 * <li>
23 * A cache name may only contain the characters {@code A-Z}, {@code a-z}, {@code ./-_$}.
24 * </li>
25 * <li>
26 * The returned cache instances are multi-thread safe.
27 * </li>
28 * </ul>
29 *
30 * @since 1.0
31 */
32 @PublicApi
33 public interface VCacheFactory
34 {
35 /**
36 * Obtains a {@link JvmCache} with the specified details.
37 *
38 * @param name the name of the cache
39 * @param settings the settings for the cache
40 * @param <K> the key type
41 * @param <V> the value type
42 * @return {@link JvmCache} with the specified details
43 */
44 @Nonnull
45 <K, V> JvmCache<K, V> getJvmCache(String name, JvmCacheSettings settings);
46
47 /**
48 * Obtains a {@link RequestCache} with the specified details.
49 *
50 * @param name the name of the cache
51 * @param <K> the key type
52 * @param <V> the value type
53 * @return {@link RequestCache} with the specified details
54 */
55 @Nonnull
56 <K, V> RequestCache<K, V> getRequestCache(String name);
57
58 /**
59 * Obtains a {@link TransactionalExternalCache} with the specified details.
60 *
61 * @param name the name of the cache
62 * @param valueMarshaller the marshaller for the values. See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
63 * @param settings the settings for the cache
64 * @param <V> the value type
65 * @return {@link TransactionalExternalCache} with the specified details
66 */
67 @Nonnull
68 <V> TransactionalExternalCache<V> getTransactionalExternalCache(
69 String name,
70 Marshaller<V> valueMarshaller,
71 ExternalCacheSettings settings);
72
73 /**
74 * Obtains a {@link StableReadExternalCache} with the specified details.
75 *
76 * @param name the name of the cache
77 * @param valueMarshaller the marshaller for the values.
78 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
79 * @param settings the settings for the cache
80 * @param <V> the value type
81 * @return {@link StableReadExternalCache} with the specified details
82 */
83 @Nonnull
84 <V> StableReadExternalCache<V> getStableReadExternalCache(
85 String name,
86 Marshaller<V> valueMarshaller,
87 ExternalCacheSettings settings);
88
89 /**
90 * Obtains a {@link DirectExternalCache} with the specified details.
91 *
92 * @param name the name of the cache
93 * @param valueMarshaller the marshaller for the values.
94 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
95 * @param settings the settings for the cache
96 * @param <V> the value type
97 * @return {@link DirectExternalCache} with the specified details
98 */
99 @Nonnull
100 <V> DirectExternalCache<V> getDirectExternalCache(
101 String name,
102 Marshaller<V> valueMarshaller,
103 ExternalCacheSettings settings);
104 }