2.7. Adding a Cache Listener - registering for cache events
JBoss Cache provides a convenient mechanism for registering notifications on cache events.
Object myListener = new MyCacheListener(); cache.addCacheListener(myListener);
Similar methods exist for removing or querying registered listeners. See the Javadocs on the
Cache
interface for more details.
Basically any public class can be used as a listener, provided it is annotated with the
@CacheListener
annotation. In addition, the class needs to have one or more methods annotated with one of the method-level annotations (in the org.jboss.cache.notifications.annotation
package). Methods annotated as such need to be public, have a void return type, and accept a single parameter of type org.jboss.cache.notifications.event.Event
or one of its subtypes.
@CacheStarted
- methods annotated such receive a notification when the cache is started. Methods need to accept a parameter type which is assignable fromCacheStartedEvent
.@CacheStopped
- methods annotated such receive a notification when the cache is stopped. Methods need to accept a parameter type which is assignable fromCacheStoppedEvent
.@NodeCreated
- methods annotated such receive a notification when a node is created. Methods need to accept a parameter type which is assignable fromNodeCreatedEvent
.@NodeRemoved
- methods annotated such receive a notification when a node is removed. Methods need to accept a parameter type which is assignable fromNodeRemovedEvent
.@NodeModified
- methods annotated such receive a notification when a node is modified. Methods need to accept a parameter type which is assignable fromNodeModifiedEvent
.@NodeMoved
- methods annotated such receive a notification when a node is moved. Methods need to accept a parameter type which is assignable fromNodeMovedEvent
.@NodeVisited
- methods annotated such receive a notification when a node is started. Methods need to accept a parameter type which is assignable fromNodeVisitedEvent
.@NodeLoaded
- methods annotated such receive a notification when a node is loaded from aCacheLoader
. Methods need to accept a parameter type which is assignable fromNodeLoadedEvent
.@NodeEvicted
- methods annotated such receive a notification when a node is evicted from memory. Methods need to accept a parameter type which is assignable fromNodeEvictedEvent
.@NodeInvalidated
- methods annotated such receive a notification when a node is evicted from memory due to a remote invalidation event. Methods need to accept a parameter type which is assignable fromNodeInvalidatedEvent
.@NodeActivated
- methods annotated such receive a notification when a node is activated. Methods need to accept a parameter type which is assignable fromNodeActivatedEvent
.@NodePassivated
- methods annotated such receive a notification when a node is passivated. Methods need to accept a parameter type which is assignable fromNodePassivatedEvent
.@TransactionRegistered
- methods annotated such receive a notification when the cache registers ajavax.transaction.Synchronization
with a registered transaction manager. Methods need to accept a parameter type which is assignable fromTransactionRegisteredEvent
.@TransactionCompleted
- 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 fromTransactionCompletedEvent
.@ViewChanged
- methods annotated such receive a notification when the group structure of the cluster changes. Methods need to accept a parameter type which is assignable fromViewChangedEvent
.@CacheBlocked
- 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 fromCacheBlockedEvent
.@CacheUnblocked
- 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 fromCacheUnblockedEvent
.@BuddyGroupChanged
- methods annotated such receive a notification when a node changes its buddy group, perhaps due to a buddy falling out of the cluster or a newer, closer buddy joining. Methods need to accept a parameter type which is assignable fromBuddyGroupChangedEvent
.
Refer to the Javadocs on the annotations as well as the
Event
subtypes for details of what is passed in to your method, and when.
Example:
@CacheListener public class MyListener { @CacheStarted @CacheStopped public void cacheStartStopEvent(Event e) { switch (e.getType()) { case CACHE_STARTED: System.out.println("Cache has started"); break; case CACHE_STOPPED: System.out.println("Cache has stopped"); break; } } @NodeCreated @NodeRemoved @NodeVisited @NodeModified @NodeMoved public void logNodeEvent(NodeEvent ne) { log("An event on node " + ne.getFqn() + " has occured"); } }
2.7.1. Synchronous and Asynchronous Notifications
By default, all notifications are synchronous, in that they happen on the thread of the caller which generated the event. As such, it is good practice to ensure cache listener implementations do not hold up the thread in long-running tasks. Alternatively, you could set the
CacheListener.sync
attribute to false
, in which case you will not be notified in the caller's thread. See the Table 12.13, “The <listeners />
Element” on tuning this thread pool and size of blocking queue.