Author: manik.surtani(a)jboss.com Date: 2008-06-03 06:48:44 -0400 (Tue, 03 Jun 2008) New Revision: 5936 Modified: core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml Log: Updated docs on cache listeners Modified: core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml 2008-06-03 10:37:56 UTC (rev 5935) +++ core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml 2008-06-03 10:48:44 UTC (rev 5936) @@ -388,23 +388,31 @@ <section id="api.listener"> <title> - Adding a CacheListener + Adding a Cache Listener - registering for cache events </title> <para> - The - <literal&gt;(a)org.jboss.cache.notifications.annotation.CacheListener&lt;/literal&gt; - annotation is a convenient - mechanism for receiving notifications from a cache about events that happen in the cache. Classes annotated - with + JBoss Cache provides a convenient mechanism for registering notifications on cache events. + </para> + <programlisting role="JAVA"><![CDATA[ + Object myListener = new MyCacheListener(); + cache.addCacheListener(myListener); + ]]></programlisting> + <para> + Similar methods exist for removing or querying registered listeners. See the javadocs on the + <literal>Cache</literal> + interface for more details. + </para> + <para> + Basically any public class can be used as a listener, provided it is annotated with the <literal>@CacheListener</literal> - need to be public classes. In addition, the class needs to have one or + annotation. 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. + or one of its subtypes. <itemizedlist> <listitem> @@ -412,7 +420,7 @@ <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> + <literal>CacheStartedEvent</literal> . </para> </listitem> @@ -422,7 +430,7 @@ <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> + <literal>CacheStoppedEvent</literal> . </para> </listitem> @@ -432,7 +440,7 @@ <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> + <literal>NodeCreatedEvent</literal> . </para> </listitem> @@ -442,7 +450,7 @@ <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> + <literal>NodeRemovedEvent</literal> . </para> </listitem> @@ -452,7 +460,7 @@ <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> + <literal>NodeModifiedEvent</literal> . </para> </listitem> @@ -462,7 +470,7 @@ <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> + <literal>NodeMovedEvent</literal> . </para> </listitem> @@ -472,7 +480,7 @@ <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> + <literal>NodeVisitedEvent</literal> . </para> </listitem> @@ -484,7 +492,7 @@ 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> + <literal>NodeLoadedEvent</literal> . </para> </listitem> @@ -494,7 +502,7 @@ <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> + <literal>NodeEvictedEvent</literal> . </para> </listitem> @@ -504,7 +512,7 @@ <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> + <literal>NodeActivatedEvent</literal> . </para> </listitem> @@ -514,7 +522,7 @@ <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> + <literal>NodePassivatedEvent</literal> . </para> </listitem> @@ -527,7 +535,7 @@ <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> + <literal>TransactionRegisteredEvent</literal> . </para> </listitem> @@ -538,7 +546,7 @@ - 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> + <literal>TransactionCompletedEvent</literal> . </para> </listitem> @@ -548,7 +556,7 @@ <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> + <literal>ViewChangedEvent</literal> . </para> </listitem> @@ -559,7 +567,7 @@ - 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> + <literal>CacheBlockedEvent</literal> . </para> </listitem> @@ -570,7 +578,7 @@ - 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> + <literal>CacheUnblockedEvent</literal> . </para> </listitem>