|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
CacheListener.java | - | - | - | - |
|
1 | package org.jboss.cache.notifications.annotation; | |
2 | ||
3 | import java.lang.annotation.ElementType; | |
4 | import java.lang.annotation.Retention; | |
5 | import java.lang.annotation.RetentionPolicy; | |
6 | import java.lang.annotation.Target; | |
7 | ||
8 | /** | |
9 | * Class-level annotation used to annotate an object as being a valid cache listener. Used with the {@link org.jboss.cache.Cache#addCacheListener(Object)} and related APIs. | |
10 | * <p/> | |
11 | * Note that even if a class is annotated with this annotation, it still needs method-level annotation (such as {@link org.jboss.cache.notifications.annotation.CacheStarted}) | |
12 | * to actually receive notifications. | |
13 | * <p/> | |
14 | * Objects annotated with this annotation - listeners - can be attached to a running {@link org.jboss.cache.Cache} so users can be notified of {@link org.jboss.cache.Cache} events. | |
15 | * <p/> | |
16 | * It is important to note that notifications happen in the same process thread as the invocation to the cache. This means that if your | |
17 | * listener implementation blocks or performs a long-running task, the original caller which triggered the cache event may block until | |
18 | * the listener callback completes. It is therefore a good idea to use the listener to be notified of an event but to perform any | |
19 | * long running tasks in a separate thread so as not to block the original caller. | |
20 | * <p/> | |
21 | * In addition, any locks acquired for the operation being performed will still be held for the callback. This needs to be kep in mind | |
22 | * as locks may be held longer than necessary or intended to and may cause deadlocking in certain situations. See above paragraph | |
23 | * on long-running tasks that should be run in a separate thread. | |
24 | * <p/> | |
25 | * Also important to note is that all data maps passed in to most listener methods as a part of the {@link org.jboss.cache.notifications.event.Event} | |
26 | * implementation are usually read-only defensive copies of the actual data stored in the cache. Therefore it is safe to | |
27 | * assume that the collections are static snapshots. If changes to the cache data are to be triggered by such events, | |
28 | * make calls on the cache directly rather than attempting to change the data maps. See the javadocs on individual method-targeted | |
29 | * annotations for more details on what is passed in. | |
30 | * <p/> | |
31 | * | |
32 | * @author <a href="mailto:manik@jboss.org">Manik Surtani</a> | |
33 | * @see CacheStarted | |
34 | * @see CacheStopped | |
35 | * @see NodeModified | |
36 | * @see NodeMoved | |
37 | * @see NodeCreated | |
38 | * @see NodeRemoved | |
39 | * @see NodeVisited | |
40 | * @see NodeLoaded | |
41 | * @see NodeEvicted | |
42 | * @see NodeActivated | |
43 | * @see NodePassivated | |
44 | * @see ViewChanged | |
45 | * @see CacheBlocked | |
46 | * @see CacheUnblocked | |
47 | * @see TransactionCompleted | |
48 | * @see TransactionRegistered | |
49 | * @see org.jboss.cache.Cache#addCacheListener(Object) | |
50 | * @see org.jboss.cache.Cache#addCacheListener(org.jboss.cache.Fqn,Object) | |
51 | * @see org.jboss.cache.Cache#removeCacheListener(Object) | |
52 | * @see org.jboss.cache.Cache#removeCacheListener(org.jboss.cache.Fqn,Object) | |
53 | * @see org.jboss.cache.Cache#getCacheListeners() | |
54 | * @see org.jboss.cache.Cache#getCacheListeners(org.jboss.cache.Fqn) | |
55 | * @since 2.0.0 | |
56 | */ | |
57 | @Retention(RetentionPolicy.RUNTIME) | |
58 | @Target(ElementType.TYPE) | |
59 | public @interface CacheListener | |
60 | { | |
61 | } |
|