1 package com.atlassian.vcache;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.marshalling.api.MarshallingPair;
5
6 /**
7 * Represents the factory for creating caches.
8 * <p>
9 * Notes:
10 * </p>
11 * <ul>
12 * <li>
13 * {@link JvmCache}'s and {@link RequestCache}'s are identified by their name and cache type. I.e. A
14 * {@link JvmCache} called <tt>'Williams'</tt> and a {@link RequestCache} called <tt>'Williams'</tt> are
15 * considered to be separate caches.
16 * </li>
17 * <li>
18 * {@link ExternalCache}'s are identified by their name and cache type.
19 * </li>
20 * <li>
21 * A cache name may only contain the characters {@code A-Z}, {@code a-z}, {@code 0-9}, {@code ./-_$}.
22 * </li>
23 * <li>
24 * The returned cache instances are multi-thread safe.
25 * </li>
26 * </ul>
27 *
28 * @since 1.0
29 */
30 @PublicApi
31 public interface VCacheFactory {
32 /**
33 * Obtains a {@link JvmCache} with the specified details.
34 * <p>
35 * Note: multiple calls to this method will always return the instance created on the first invocation. As such,
36 * any changes in the supplied settings will be ignored.
37 * </p>
38 *
39 * @param name the name of the cache
40 * @param settings the settings for the cache
41 * @param <K> the key type
42 * @param <V> the value type
43 * @return {@link JvmCache} with the specified details
44 */
45 <K, V> JvmCache<K, V> getJvmCache(String name, JvmCacheSettings settings);
46
47 /**
48 * Obtains a {@link RequestCache} with the specified details.
49 * <p>
50 * Note: multiple calls to this method will always return the instance created on the first invocation.
51 * </p>
52 *
53 * @param name the name of the cache
54 * @param <K> the key type
55 * @param <V> the value type
56 * @return {@link RequestCache} with the specified details
57 */
58 <K, V> RequestCache<K, V> getRequestCache(String name);
59
60 /**
61 * Obtains a {@link TransactionalExternalCache} with the specified details.
62 * <p>
63 * Note: each call to this method will return a new instance using the specified settings. However, the existing
64 * data stored in the external cache will remain. It is not expected in a production configuration that this
65 * method will be called multiple times, but is allowed is a development configuration.
66 * </p>
67 *
68 * @param name the name of the cache
69 * @param valueMarshaller the marshaller for the values.
70 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
71 * @param settings the settings for the cache
72 * @param <V> the value type
73 * @return {@link TransactionalExternalCache} with the specified details
74 * @deprecated since 1.5.0. Use {@link #getTransactionalExternalCache(String, MarshallingPair, ExternalCacheSettings)}
75 */
76 @Deprecated
77 <V> TransactionalExternalCache<V> getTransactionalExternalCache(
78 String name,
79 Marshaller<V> valueMarshaller,
80 ExternalCacheSettings settings);
81
82 /**
83 * Obtains a {@link TransactionalExternalCache} with the specified details.
84 * <p>
85 * Note: each call to this method will return a new instance using the specified settings. However, the existing
86 * data stored in the external cache will remain. It is not expected in a production configuration that this
87 * method will be called multiple times, but is allowed is a development configuration.
88 * </p>
89 *
90 * @param name the name of the cache
91 * @param valueMarshalling the marshaller for the values.
92 * @param settings the settings for the cache
93 * @param <V> the value type
94 * @return {@link TransactionalExternalCache} with the specified details
95 */
96 <V> TransactionalExternalCache<V> getTransactionalExternalCache(
97 String name,
98 MarshallingPair<V> valueMarshalling,
99 ExternalCacheSettings settings);
100
101 /**
102 * Obtains a {@link StableReadExternalCache} with the specified details.
103 * <p>
104 * Note: each call to this method will return a new instance using the specified settings. However, the existing
105 * data stored in the external cache will remain. It is not expected in a production configuration that this
106 * method will be called multiple times, but is allowed is a development configuration.
107 * </p>
108 *
109 * @param name the name of the cache
110 * @param valueMarshaller the marshaller for the values.
111 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
112 * @param settings the settings for the cache
113 * @param <V> the value type
114 * @return {@link StableReadExternalCache} with the specified details
115 * @deprecated since 1.5.0. Use {@link #getStableReadExternalCache(String, MarshallingPair, ExternalCacheSettings)}
116 */
117 @Deprecated
118 <V> StableReadExternalCache<V> getStableReadExternalCache(
119 String name,
120 Marshaller<V> valueMarshaller,
121 ExternalCacheSettings settings);
122
123 /**
124 * Obtains a {@link StableReadExternalCache} with the specified details.
125 * <p>
126 * Note: each call to this method will return a new instance using the specified settings. However, the existing
127 * data stored in the external cache will remain. It is not expected in a production configuration that this
128 * method will be called multiple times, but is allowed is a development configuration.
129 * </p>
130 *
131 * @param name the name of the cache
132 * @param valueMarshalling the marshalling pair for the values.
133 * @param settings the settings for the cache
134 * @param <V> the value type
135 * @return {@link StableReadExternalCache} with the specified details
136 */
137 <V> StableReadExternalCache<V> getStableReadExternalCache(
138 String name,
139 MarshallingPair<V> valueMarshalling,
140 ExternalCacheSettings settings);
141
142 /**
143 * Obtains a {@link DirectExternalCache} with the specified details.
144 * <p>
145 * Note: each call to this method will return a new instance using the specified settings. However, the existing
146 * data stored in the external cache will remain. It is not expected in a production configuration that this
147 * method will be called multiple times, but is allowed is a development configuration.
148 * </p>
149 *
150 * @param name the name of the cache
151 * @param valueMarshaller the marshaller for the values.
152 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
153 * @param settings the settings for the cache
154 * @param <V> the value type
155 * @return {@link DirectExternalCache} with the specified details
156 * @deprecated since 1.5.0. Use {@link #getDirectExternalCache(String, MarshallingPair, ExternalCacheSettings)}
157 */
158 @Deprecated
159 <V> DirectExternalCache<V> getDirectExternalCache(
160 String name,
161 Marshaller<V> valueMarshaller,
162 ExternalCacheSettings settings);
163
164 /**
165 * Obtains a {@link DirectExternalCache} with the specified details.
166 * <p>
167 * Note: each call to this method will return a new instance using the specified settings. However, the existing
168 * data stored in the external cache will remain. It is not expected in a production configuration that this
169 * method will be called multiple times, but is allowed is a development configuration.
170 * </p>
171 *
172 * @param name the name of the cache
173 * @param valueMarshalling the marshalling pair to be used for marshalling.
174 * @param settings the settings for the cache
175 * @param <V> the value type
176 * @return {@link DirectExternalCache} with the specified details
177 */
178 <V> DirectExternalCache<V> getDirectExternalCache(
179 String name,
180 MarshallingPair<V> valueMarshalling,
181 ExternalCacheSettings settings);
182 }