Clover coverage report -
Coverage timestamp: Thu Jul 5 2007 20:02:32 EDT
file stats: LOC: 61   Methods: 0
NCLOC: 10   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
CacheListener.java - - - -
coverage
 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    }