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 from CacheStartedEvent .
@CacheStopped - methods annotated such receive a notification when the cache is stopped. Methods need to accept a parameter type which is assignable from CacheStoppedEvent .
@NodeCreated - methods annotated such receive a notification when a node is created. Methods need to accept a parameter type which is assignable from NodeCreatedEvent .
@NodeRemoved - methods annotated such receive a notification when a node is removed. Methods need to accept a parameter type which is assignable from NodeRemovedEvent .
@NodeModified - methods annotated such receive a notification when a node is modified. Methods need to accept a parameter type which is assignable from NodeModifiedEvent .
@NodeMoved - methods annotated such receive a notification when a node is moved. Methods need to accept a parameter type which is assignable from NodeMovedEvent .
@NodeVisited - methods annotated such receive a notification when a node is started. Methods need to accept a parameter type which is assignable from NodeVisitedEvent .
@NodeLoaded - methods annotated such receive a notification when a node is loaded from a CacheLoader . Methods need to accept a parameter type which is assignable from NodeLoadedEvent .
@NodeEvicted - methods annotated such receive a notification when a node is evicted from memory. Methods need to accept a parameter type which is assignable from NodeEvictedEvent .
@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 from NodeInvalidatedEvent .
@NodeActivated - methods annotated such receive a notification when a node is activated. Methods need to accept a parameter type which is assignable from NodeActivatedEvent .
@NodePassivated - methods annotated such receive a notification when a node is passivated. Methods need to accept a parameter type which is assignable from NodePassivatedEvent .
@TransactionRegistered - methods annotated such receive a notification when the cache registers a javax.transaction.Synchronization with a registered transaction manager. Methods need to accept a parameter type which is assignable from TransactionRegisteredEvent .
@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 from TransactionCompletedEvent .
@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 from ViewChangedEvent .
@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 from CacheBlockedEvent .
@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 from CacheUnblockedEvent .
@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 from BuddyGroupChangedEvent.

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 practise to ensure cache listener implementations don't 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 11.13, “The <listeners /> Element” on tuning this thread pool and size of blocking queue.