Proposed Annotation Based Core Cache Listener API

This is the rough draft for the recommended API changes to the notification system in core cache.

Please post feedback to http://www.jboss.com/index.html?module=bb&op=viewtopic&t=111094

Recommended Changes

• Use annotations and remove interface requirements

• Put notification data in a class instead of parameters

• Use a common notification base class

Advantages over existing API

• Easy to use - Very few lines of code required

• Not Object Model Invasive - no interface or inheritance requirements

• Very Flexible - Can be used in a variety of ways

• Very Extensible - New notifications can be introduced by just adding a new annotation and a new object. The old interface approach would require a new interface to be introduced every time we enhance the API since adding methods would break backwards compatibility. Also additional data can easily be added to a notification unlike the previous approach which relied on a specific method signature.

Reasons to change

• We already need 2 new notifications types for our own internal reasons (POJO Cache & Session Replication)

• We also need additional data to be added to some notifications

• Customers will be able to take advantage of the added benefits in the 2.0.0.GA release

• It is likely we will have to switch to a better API in the future anyway

Examples

The following are example cases using the proposed API

Simple Case

We only want modify events. Therefore we can use the expected subclass:

@CacheListener
public class MyCacheListener
{
   ...

   @NodeModified
   public void myMethod(NodeModifyEvent e)
   {
      log.info("FQN: " + e.getFqn());
      log.info("Modification type: " + e.getModificationType());
      log.info("Data: " + e.getData());
   }
}

Dynamic Case

We want several notifications on one method, so we use the base Notification class:

@CacheListener
public class MyCacheListener
{
   ...

   @NodeModified
   @NodeVisited
   @NodeCreated
   @NodeRemoved
   @ViewChanged
   @TransactionRegistered
   @TransactionCompleted
   public void myMethod(Event e)
   {
      log.info("Event type: " + e.getType());
      
      if (e.getType() == Event.Type.VIEW_CHANGED)
      {
         View newView = ((ViewChangedEvent) e).getNewView();   
      }

   }
}

Mixed Case

We use multiple methods to receive the same notification, one receives another notification as well:

@CacheListener
public class MyCacheListener
{
   ...

   @NodeModified
   public void logModify(NodeModifiedEvent e)
   {
      log.info("FQN: " + e.getFqn());
      log.info("Modification type: " + e.getModificationType());
      log.info("New Data: " + e.getData());
   }

   @NodeModified
   @NodeVisited
   public void sendJMSMessage(Event e)
   {
      ObjectMessage message = session.createObjectMessage();
      message.setOjbect(e);
   }

}