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. Simply calls
51 * {@link VCacheFactory#getRequestCache(String, RequestCacheSettings)} using the default settings.
52 *
53 * </p>
54 *
55 * @param name the name of the cache
56 * @param <K> the key type
57 * @param <V> the value type
58 * @return {@link RequestCache} with the specified details
59 * @deprecated Please use {@link VCacheFactory#getRequestCache(String, RequestCacheSettings)} instead.
60 */
61 @Deprecated
62 default <K, V> RequestCache<K, V> getRequestCache(String name) {
63 return getRequestCache(name, new RequestCacheSettingsBuilder().build());
64 }
65
66 /**
67 * Obtains a {@link RequestCache} with the specified settings.
68 *
69 * @param name the name of the cache.
70 * @param settings the settings for this cache.
71 * @param <K> the key type.
72 * @param <V> the value type.
73 * @return {@link RequestCache} with the specified configuration.
74 */
75 <K, V> RequestCache<K, V> getRequestCache(String name, RequestCacheSettings settings);
76
77 /**
78 * Obtains a {@link TransactionalExternalCache} with the specified details.
79 * <p>
80 * Note: each call to this method will return a new instance using the specified settings. However, the existing
81 * data stored in the external cache will remain. It is not expected in a production configuration that this
82 * method will be called multiple times, but is allowed is a development configuration.
83 * </p>
84 *
85 * @param name the name of the cache
86 * @param valueMarshaller the marshaller for the values.
87 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
88 * @param settings the settings for the cache
89 * @param <V> the value type
90 * @return {@link TransactionalExternalCache} with the specified details
91 * @deprecated since 1.5.0. Use {@link #getTransactionalExternalCache(String, MarshallingPair, ExternalCacheSettings)}
92 */
93 @Deprecated
94 <V> TransactionalExternalCache<V> getTransactionalExternalCache(
95 String name,
96 Marshaller<V> valueMarshaller,
97 ExternalCacheSettings settings);
98
99 /**
100 * Obtains a {@link TransactionalExternalCache} with the specified details.
101 * <p>
102 * Note: each call to this method will return a new instance using the specified settings. However, the existing
103 * data stored in the external cache will remain. It is not expected in a production configuration that this
104 * method will be called multiple times, but is allowed is a development configuration.
105 * </p>
106 *
107 * @param name the name of the cache
108 * @param valueMarshalling the marshaller for the values.
109 * @param settings the settings for the cache
110 * @param <V> the value type
111 * @return {@link TransactionalExternalCache} with the specified details
112 */
113 <V> TransactionalExternalCache<V> getTransactionalExternalCache(
114 String name,
115 MarshallingPair<V> valueMarshalling,
116 ExternalCacheSettings settings);
117
118 /**
119 * Obtains a {@link StableReadExternalCache} with the specified details.
120 * <p>
121 * Note: each call to this method will return a new instance using the specified settings. However, the existing
122 * data stored in the external cache will remain. It is not expected in a production configuration that this
123 * method will be called multiple times, but is allowed is a development configuration.
124 * </p>
125 *
126 * @param name the name of the cache
127 * @param valueMarshaller the marshaller for the values.
128 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
129 * @param settings the settings for the cache
130 * @param <V> the value type
131 * @return {@link StableReadExternalCache} with the specified details
132 * @deprecated since 1.5.0. Use {@link #getStableReadExternalCache(String, MarshallingPair, ExternalCacheSettings)}
133 */
134 @Deprecated
135 <V> StableReadExternalCache<V> getStableReadExternalCache(
136 String name,
137 Marshaller<V> valueMarshaller,
138 ExternalCacheSettings settings);
139
140 /**
141 * Obtains a {@link StableReadExternalCache} with the specified details.
142 * <p>
143 * Note: each call to this method will return a new instance using the specified settings. However, the existing
144 * data stored in the external cache will remain. It is not expected in a production configuration that this
145 * method will be called multiple times, but is allowed is a development configuration.
146 * </p>
147 *
148 * @param name the name of the cache
149 * @param valueMarshalling the marshalling pair for the values.
150 * @param settings the settings for the cache
151 * @param <V> the value type
152 * @return {@link StableReadExternalCache} with the specified details
153 */
154 <V> StableReadExternalCache<V> getStableReadExternalCache(
155 String name,
156 MarshallingPair<V> valueMarshalling,
157 ExternalCacheSettings settings);
158
159 /**
160 * Obtains a {@link DirectExternalCache} with the specified details.
161 * <p>
162 * Note: each call to this method will return a new instance using the specified settings. However, the existing
163 * data stored in the external cache will remain. It is not expected in a production configuration that this
164 * method will be called multiple times, but is allowed is a development configuration.
165 * </p>
166 *
167 * @param name the name of the cache
168 * @param valueMarshaller the marshaller for the values.
169 * See {@link com.atlassian.vcache.marshallers.MarshallerFactory} for provided implementations.
170 * @param settings the settings for the cache
171 * @param <V> the value type
172 * @return {@link DirectExternalCache} with the specified details
173 * @deprecated since 1.5.0. Use {@link #getDirectExternalCache(String, MarshallingPair, ExternalCacheSettings)}
174 */
175 @Deprecated
176 <V> DirectExternalCache<V> getDirectExternalCache(
177 String name,
178 Marshaller<V> valueMarshaller,
179 ExternalCacheSettings settings);
180
181 /**
182 * Obtains a {@link DirectExternalCache} with the specified details.
183 * <p>
184 * Note: each call to this method will return a new instance using the specified settings. However, the existing
185 * data stored in the external cache will remain. It is not expected in a production configuration that this
186 * method will be called multiple times, but is allowed is a development configuration.
187 * </p>
188 *
189 * @param name the name of the cache
190 * @param valueMarshalling the marshalling pair to be used for marshalling.
191 * @param settings the settings for the cache
192 * @param <V> the value type
193 * @return {@link DirectExternalCache} with the specified details
194 */
195 <V> DirectExternalCache<V> getDirectExternalCache(
196 String name,
197 MarshallingPair<V> valueMarshalling,
198 ExternalCacheSettings settings);
199 }