|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
Cache.java | - | - | - | - |
|
1 | /* | |
2 | * JBoss, Home of Professional Open Source | |
3 | * | |
4 | * Distributable under LGPL license. | |
5 | * See terms of license at gnu.org. | |
6 | */ | |
7 | package org.jboss.cache; | |
8 | ||
9 | import net.jcip.annotations.ThreadSafe; | |
10 | import org.jboss.cache.config.Configuration; | |
11 | import org.jgroups.Address; | |
12 | ||
13 | import java.util.List; | |
14 | import java.util.Map; | |
15 | import java.util.Set; | |
16 | ||
17 | /** | |
18 | * Interface for a Cache where data mappings are grouped and stored in a tree data | |
19 | * structure consisting of {@link Node}s. | |
20 | * <p/> | |
21 | * This is the central construct and basic client API of JBoss Cache and is used for | |
22 | * cache-wide operations. | |
23 | * <p/> | |
24 | * The cache is constructed using a {@link CacheFactory} and is started | |
25 | * using {@link #start}, if not already started by the CacheFactory. | |
26 | * <p/> | |
27 | * Once constructed, the Cache interface can be used to create or access {@link Node}s, which contain data. Once references | |
28 | * to {@link Node}s are obtained, data can be stored in them, | |
29 | * <p/> | |
30 | * As a convenience (and mainly to provide a familiar API to the older JBoss Cache 1.x.x releases) methods are provided that | |
31 | * operate directly on nodes. | |
32 | * <ul> | |
33 | * <li>{@link #put(Fqn,Object,Object)} </li> | |
34 | * <li>{@link #put(Fqn,java.util.Map)} </li> | |
35 | * <li>{@link #get(Fqn,Object)} </li> | |
36 | * <li>{@link #remove(Fqn,Object)} </li> | |
37 | * <li>{@link #removeNode(Fqn)} </li> | |
38 | * </ul> | |
39 | * <p/> | |
40 | * A simple example of usage: | |
41 | * <pre> | |
42 | * // creates with default settings and starts the cache | |
43 | * Cache cache = DefaultCacheFactory.getInstance().createCache(); | |
44 | * Fqn personRecords = Fqn.fromString("/org/mycompany/personRecords"); | |
45 | * <p/> | |
46 | * Node rootNode = cache.getRoot(); | |
47 | * Node personRecordsNode = rootNode.addChild(personRecords); | |
48 | * <p/> | |
49 | * // now add some person records. | |
50 | * Fqn peterGriffin = Fqn.fromString("/peterGriffin"); | |
51 | * Fqn stewieGriffin = Fqn.fromString("/stewieGriffin"); | |
52 | * <p/> | |
53 | * // the addChild() API uses relative Fqns | |
54 | * Node peter = personRecordsNode.addChild(peterGriffin); | |
55 | * Node stewie = personRecordsNode.addChild(stewieGriffin); | |
56 | * <p/> | |
57 | * peter.put("name", "Peter Griffin"); | |
58 | * peter.put("ageGroup", "MidLifeCrisis"); | |
59 | * peter.put("homicidal", Boolean.FALSE); | |
60 | * <p/> | |
61 | * stewie.put("name", "Stewie Griffin"); | |
62 | * stewie.put("ageGroup", "Infant"); | |
63 | * stewie.put("homicidal", Boolean.TRUE); | |
64 | * <p/> | |
65 | * peter.getFqn().toString(); // will print out /org/mycompany/personRecords/peterGriffin | |
66 | * stewie.getFqn().toString(); // will print out /org/mycompany/personRecords/stewieGriffin | |
67 | * <p/> | |
68 | * peter.getFqn().getParent().equals(stewie.getFqn().getParent()); // will return true | |
69 | * <p/> | |
70 | * </pre> | |
71 | * <p/> | |
72 | * For more information, please read the JBoss Cache user guide and tutorial, available on <a href="http://labs.jboss.com/portal/jbosscache/docs/index.html" target="_BLANK">the JBoss Cache documentation site</a>, | |
73 | * and look through the examples <a href="http://labs.jboss.com/portal/jbosscache/download/index.html" target="_BLANK">shipped with the JBoss Cache distribution</a>. | |
74 | * | |
75 | * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a> | |
76 | * @see Node | |
77 | * @see CacheFactory | |
78 | * @since 2.0.0 | |
79 | */ | |
80 | @ThreadSafe | |
81 | public interface Cache<K, V> | |
82 | { | |
83 | /** | |
84 | * Retrieves the configuration of this cache. | |
85 | * | |
86 | * @return the configuration. | |
87 | */ | |
88 | Configuration getConfiguration(); | |
89 | ||
90 | /** | |
91 | * Returns the root node of this cache. | |
92 | * | |
93 | * @return the root node | |
94 | */ | |
95 | Node<K, V> getRoot(); | |
96 | ||
97 | /** | |
98 | * Adds a {@link CacheListener} to the entire cache. The object passed in needs to be properly annotated with the | |
99 | * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown. | |
100 | * | |
101 | * @param listener listener to add | |
102 | */ | |
103 | void addCacheListener(Object listener); | |
104 | ||
105 | /** | |
106 | * Adds a {@link CacheListener} to a given region. The object passed in needs to be properly annotated with the | |
107 | * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown. | |
108 | * | |
109 | * @param region region to add listener to | |
110 | * @param listener listener to add | |
111 | */ | |
112 | void addCacheListener(Fqn<?> region, Object listener); | |
113 | ||
114 | /** | |
115 | * Removes a {@link CacheListener} from the cache. The object passed in needs to be properly annotated with the | |
116 | * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown. | |
117 | * | |
118 | * @param listener listener to remove | |
119 | */ | |
120 | void removeCacheListener(Object listener); | |
121 | ||
122 | /** | |
123 | * Removes a {@link CacheListener} from a given region. The object passed in needs to be properly annotated with the | |
124 | * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown. | |
125 | * | |
126 | * @param region region from which to remove listener | |
127 | * @param listener listener to remove | |
128 | */ | |
129 | void removeCacheListener(Fqn<?> region, Object listener); | |
130 | ||
131 | /** | |
132 | * Retrieves an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to the cache. | |
133 | * | |
134 | * @return an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to the cache. | |
135 | */ | |
136 | Set<Object> getCacheListeners(); | |
137 | ||
138 | /** | |
139 | * Retrieves an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to a specific region. | |
140 | * | |
141 | * @return an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to a specific region. | |
142 | */ | |
143 | Set<Object> getCacheListeners(Fqn<?> region); | |
144 | ||
145 | /** | |
146 | * Associates the specified value with the specified key for a {@link Node} in this cache. | |
147 | * If the {@link Node} previously contained a mapping for this key, the old value is replaced by the specified value. | |
148 | * | |
149 | * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed. | |
150 | * @param key key with which the specified value is to be associated. | |
151 | * @param value value to be associated with the specified key. | |
152 | * @return previous value associated with specified key, or <code>null</code> if there was no mapping for key. | |
153 | * A <code>null</code> return can also indicate that the Node previously associated <code>null</code> with the specified key, if the implementation supports null values. | |
154 | */ | |
155 | V put(Fqn<?> fqn, K key, V value); | |
156 | ||
157 | /** | |
158 | * Under special operating behavior, associates the value with the specified key for a node identified by the Fqn passed in. | |
159 | * <ul> | |
160 | * <li> Only goes through if the node specified does not exist; no-op otherwise.</i> | |
161 | * <li> Force asynchronous mode for replication or invalidation to prevent any blocking.</li> | |
162 | * <li> 0ms lock timeout to prevent any blocking here either. If the lock is not acquired, this method is a no-op, and swallows the timeout exception.</li> | |
163 | * <li> Ongoing transactions are suspended before this call, so failures here will not affect any ongoing transactions.</li> | |
164 | * <li> Errors and exceptions are 'silent' - logged at a much lower level than normal, and this method does not throw exceptions</li> | |
165 | * </ul> | |
166 | * This method is for caching data that has an external representation in storage, where, concurrent modification and | |
167 | * transactions are not a consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome' | |
168 | * rather than a 'failing outcome'. | |
169 | * <p/> | |
170 | * An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached before | |
171 | * returning the data to the caller. Subsequent calls would prefer to get the data from the cache and if the data doesn't exist | |
172 | * in the cache, fetch again from the legacy datastore. | |
173 | * <p/> | |
174 | * See <a href="http://jira.jboss.com/jira/browse/JBCACHE-848">JBCACHE-848</a> for details around this feature. | |
175 | * <p/> | |
176 | * | |
177 | * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed. | |
178 | * @param key key with which the specified value is to be associated. | |
179 | * @param value value to be associated with the specified key. | |
180 | */ | |
181 | void putForExternalRead(Fqn<?> fqn, K key, V value); | |
182 | ||
183 | /** | |
184 | * Copies all of the mappings from the specified map to a {@link Node}. | |
185 | * | |
186 | * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to copy the data to | |
187 | * @param data mappings to copy | |
188 | */ | |
189 | void put(Fqn<?> fqn, Map<K, V> data); | |
190 | ||
191 | /** | |
192 | * Removes the mapping for this key from a Node. | |
193 | * Returns the value to which the Node previously associated the key, or | |
194 | * <code>null</code> if the Node contained no mapping for this key. | |
195 | * | |
196 | * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed. | |
197 | * @param key key whose mapping is to be removed from the Node | |
198 | * @return previous value associated with specified Node's key | |
199 | */ | |
200 | V remove(Fqn<?> fqn, K key); | |
201 | ||
202 | /** | |
203 | * Removes a {@link Node} indicated by absolute {@link Fqn}. | |
204 | * | |
205 | * @param fqn {@link Node} to remove | |
206 | * @return true if the node was removed, false if the node was not found | |
207 | */ | |
208 | boolean removeNode(Fqn<?> fqn); | |
209 | ||
210 | /** | |
211 | * Convenience method that allows for direct access to the data in a {@link Node}. | |
212 | * | |
213 | * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed. | |
214 | * @param key key under which value is to be retrieved. | |
215 | * @return returns data held under specified key in {@link Node} denoted by specified Fqn. | |
216 | */ | |
217 | V get(Fqn<?> fqn, K key); | |
218 | ||
219 | /** | |
220 | * Eviction call that evicts the specified {@link Node} from memory. | |
221 | * | |
222 | * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be evicted. | |
223 | * @param recursive evicts children as well | |
224 | */ | |
225 | void evict(Fqn<?> fqn, boolean recursive); | |
226 | ||
227 | /** | |
228 | * Retrieves a {@link Region} for a given {@link Fqn}. If the region does not exist, | |
229 | * and <li>createIfAbsent</li> is true, then one is created. | |
230 | * <p/> | |
231 | * If not, parent Fqns will be consulted in turn for registered regions, gradually working up to | |
232 | * Fqn.ROOT. If no regions are defined in any of the parents either, a null is returned. | |
233 | * | |
234 | * @param fqn Fqn that is contained in a region. | |
235 | * @param createIfAbsent If true, will create a new associated region if not found. | |
236 | * @return a MarshRegion. Null if none is found. | |
237 | * @throws UnsupportedOperationException if the region cannot be defined. | |
238 | * @see Region | |
239 | */ | |
240 | Region getRegion(Fqn<?> fqn, boolean createIfAbsent); | |
241 | ||
242 | /** | |
243 | * Removes a region denoted by the Fqn passed in. | |
244 | * | |
245 | * @param fqn of the region to remove | |
246 | * @return true if a region did exist and was removed; false otherwise. | |
247 | */ | |
248 | boolean removeRegion(Fqn<?> fqn); | |
249 | ||
250 | /** | |
251 | * Lifecycle method that initializes configuration state, the root node, etc. | |
252 | * | |
253 | * @throws CacheException if there are creation problems | |
254 | */ | |
255 | void create() throws CacheException; | |
256 | ||
257 | /** | |
258 | * Lifecycle method that starts the cache loader, | |
259 | * starts cache replication, starts the region manager, etc. | |
260 | * | |
261 | * @throws CacheException if there are startup problems | |
262 | */ | |
263 | void start() throws CacheException; | |
264 | ||
265 | /** | |
266 | * Lifecycle method that stops the cache, including replication, | |
267 | * clustering, cache loading, notifications, etc. | |
268 | */ | |
269 | void stop(); | |
270 | ||
271 | /** | |
272 | * Lifecycle method that clears state. | |
273 | * Cache can then be restarted using {@link #start}. | |
274 | */ | |
275 | void destroy(); | |
276 | ||
277 | /** | |
278 | * Gets where the cache currently is its lifecycle transitions. | |
279 | * | |
280 | * @return the CacheStatus. Will not return <code>null</code>. | |
281 | */ | |
282 | CacheStatus getCacheStatus(); | |
283 | ||
284 | /** | |
285 | * @return the current invocation context for the current invocation and cache instance. | |
286 | * @see org.jboss.cache.InvocationContext | |
287 | */ | |
288 | InvocationContext getInvocationContext(); | |
289 | ||
290 | /** | |
291 | * Sets the passed in {@link org.jboss.cache.InvocationContext} as current. | |
292 | * | |
293 | * @param ctx invocation context to use | |
294 | */ | |
295 | void setInvocationContext(InvocationContext ctx); | |
296 | ||
297 | /** | |
298 | * Returns the local address of this cache in a cluster, or <code>null</code> | |
299 | * if running in local mode. | |
300 | * | |
301 | * @return the local address of this cache in a cluster, or <code>null</code> | |
302 | * if running in local mode. | |
303 | */ | |
304 | Address getLocalAddress(); | |
305 | ||
306 | /** | |
307 | * Returns a list of members in the cluster, or <code>null</code> | |
308 | * if running in local mode. | |
309 | * | |
310 | * @return a {@link List} of members in the cluster, or <code>null</code> | |
311 | * if running in local mode. | |
312 | */ | |
313 | List<Address> getMembers(); | |
314 | ||
315 | /** | |
316 | * Moves a part of the cache to a different subtree. | |
317 | * <p/> | |
318 | * E.g.: | |
319 | * <p/> | |
320 | * assume a cache structure such as: | |
321 | * <p/> | |
322 | * <pre> | |
323 | * /a/b/c | |
324 | * /a/b/d | |
325 | * /a/b/e | |
326 | * <p/> | |
327 | * <p/> | |
328 | * Fqn f1 = Fqn.fromString("/a/b/c"); | |
329 | * Fqn f2 = Fqn.fromString("/a/b/d"); | |
330 | * <p/> | |
331 | * cache.move(f1, f2); | |
332 | * </pre> | |
333 | * <p/> | |
334 | * Will result in: | |
335 | * <pre> | |
336 | * <p/> | |
337 | * /a/b/d/c | |
338 | * /a/b/e | |
339 | * <p/> | |
340 | * </pre> | |
341 | * <p/> | |
342 | * and now | |
343 | * <p/> | |
344 | * <pre> | |
345 | * Fqn f3 = Fqn.fromString("/a/b/e"); | |
346 | * Fqn f4 = Fqn.fromString("/a"); | |
347 | * cache.move(f3, f4); | |
348 | * </pre> | |
349 | * <p/> | |
350 | * will result in: | |
351 | * <pre> | |
352 | * /a/b/d/c | |
353 | * /a/e | |
354 | * </pre> | |
355 | * No-op if the node to be moved is the root node. | |
356 | * | |
357 | * @param nodeToMove the Fqn of the node to move. | |
358 | * @param newParent new location under which to attach the node being moved. | |
359 | * @throws NodeNotExistsException may throw one of these if the target node does not exist or if a different thread has moved this node elsewhere already. | |
360 | */ | |
361 | void move(Fqn<?> nodeToMove, Fqn<?> newParent) throws NodeNotExistsException; | |
362 | ||
363 | /** | |
364 | * Returns the version of the cache as a string. | |
365 | * | |
366 | * @return the version string of the cache. | |
367 | * @see Version#printVersion | |
368 | */ | |
369 | String getVersion(); | |
370 | } |
|