[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
manik at jboss.org
Fri Jun 29 14:22:40 EDT 2007
User: msurtani
Date: 07/06/29 14:22:40
Modified: docs/JBossCache-UserGuide/en/modules basic_api.xml
Log:
Updated docs to reflect annotation based listeners
Revision Changes Path
1.11 +179 -42 JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: basic_api.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- basic_api.xml 31 May 2007 05:22:36 -0000 1.10
+++ basic_api.xml 29 Jun 2007 18:22:40 -0000 1.11
@@ -303,8 +303,7 @@
every time data is changed in a cache other caches in the cluster
receive a message informing them that their data is now stale and should
be evicted from memory. This reduces replication overhead while still being able to invalidate stale data
- on
- remote caches.
+ on remote caches.
</listitem>
<listitem>
<emphasis>INVALIDATION_ASYNC</emphasis>
@@ -325,47 +324,185 @@
Adding a CacheListener
</title>
<para>
+ The <literal>@org.jboss.cache.notifications.annotation.CacheListener</literal> annotation is a convenient
+ mechanism for receiving notifications from a cache about events that happen in the cache. Classes annotated
+ with <literal>@CacheListener</literal> need to be public classes. In addition, the class needs to have one or
+ more methods annotated with one of the method-level annotations (in the <literal>org.jboss.cache.notifications.annotation</literal>
+ package). Methods annotated as such need to be public, have a void return type, and accept a single parameter of
+ type <literal>org.jboss.cache.notifications.event.Event</literal> or one of it's subtypes.
- The
- <literal>org.jboss.cache.CacheListener</literal>
- interface is a convenient mechanism for receiving notifications from a Cache
- about events that happen in the Cache. The interface may be implemented directly, or as a convenience,
- <literal>org.jboss.cache.AbstractCacheListener</literal>
- can be extended.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/Listeners.png" format="PNG"/>
- </imageobject>
- </mediaobject>
-
-
- <literal>AbstractCacheListener</literal>
- implements all the methods in
- <literal>CacheListener</literal>
- as no-ops, so you could just override the callbacks
- that you are interested in.
- <programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>@CacheStarted</literal> - methods annotated such receive a notification when the cache is
+ started. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.CacheStartedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@CacheStopped</literal> - methods annotated such receive a notification when the cache is
+ stopped. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.CacheStoppedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeCreated</literal> - methods annotated such receive a notification when a node is
+ created. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeCreatedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeRemoved</literal> - methods annotated such receive a notification when a node is
+ removed. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeRemovedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeModified</literal> - methods annotated such receive a notification when a node is
+ modified. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeModifiedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeMoved</literal> - methods annotated such receive a notification when a node is
+ moved. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeMovedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeVisited</literal> - methods annotated such receive a notification when a node is
+ started. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeVisitedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeLoaded</literal> - methods annotated such receive a notification when a node is
+ loaded from a <literal>CacheLoader</literal>. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeLoadedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeEvicted</literal> - methods annotated such receive a notification when a node is
+ evicted from memory. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeEvictedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodeActivated</literal> - methods annotated such receive a notification when a node is
+ activated. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeActivatedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@NodePassivated</literal> - methods annotated such receive a notification when a node is
+ passivated. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodePassivatedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@TransactionRegistered</literal> - methods annotated such receive a notification when the cache
+ registers a <literal>javax.transaction.Synchronization</literal> with a registered transaction manager.
+ Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.TransactionRegisteredEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@TransactionCompleted</literal> - methods annotated such receive a notification when the cache
+ receives a commit or rollback call from a registered transaction manager.
+ Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.TransactionCompletedEvent</literal>.
+ </para>
+ </listitem>
- CacheListener myListener = new AbstractCacheListener()
+ <listitem>
+ <para>
+ <literal>@ViewChanged</literal> - methods annotated such receive a notification when the group structure
+ of the cluster changes. Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.ViewChangedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@CacheBlocked</literal> - methods annotated such receive a notification when the cluster
+ requests that cache operations are blocked for a state transfer event. Methods need to accept a
+ parameter type which is assignable from <literal>org.jboss.cache.notifications.event.CacheBlockedEvent</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>@CacheUnblocked</literal> - methods annotated such receive a notification when the cluster
+ requests that cache operations are unblocked after a state transfer event. Methods need to accept a
+ parameter type which is assignable from <literal>org.jboss.cache.notifications.event.CacheUnblockedEvent</literal>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ <para>
+ Refer to the javadocs on the annotations as well as the <literal>Event</literal> subtypes
+ for details of what is passed in to your method, and when.
+ </para>
+ <para>
+ Example:
+ <programlisting><![CDATA[
+
+ @CacheListener
+ public class MyListener
{
- public void nodeCreated(Fqn fqn, boolean pre, boolean isLocal)
+
+ @CacheStarted
+ @CacheStopped
+ public void cacheStartStopEvent(Event e)
+ {
+ switch (e.getType())
{
- System.out.println("Node " + fqn + (pre ? "is about to be created"
- : "has been created"));
+ case Event.Type.CACHE_STARTED:
+ System.out.println("Cache has started");
+ break;
+ case Event.Type.CACHE_STOPPED:
+ System.out.println("Cache has stopped");
+ break;
+ }
}
- };
-
- cache.addCacheListener(myListener);
-
- assertTrue(cache.getCacheListeners().contains(myListener));
- </programlisting>
+ @NodeCreated
+ @NodeRemoved
+ @NodeVisited
+ @NodeModified
+ @NodeMoved
+ public void logNodeEvent(NodeEvent ne)
+ {
+ log("An event on node " + ne.getFqn() + " has occured");
+ }
+ }
- Refer to the javadocs on the
- <literal>CacheListener</literal>
- interface for details on the parameters passed in
- to each of the callback methods.
+ ]]></programlisting>
</para>
</section>
More information about the jboss-cvs-commits
mailing list