[jboss-user] [JBoss Cache] Document updated/added: "JBossCacheListenerAPIProposal"

[Manik Surtani]

User development,

The document "JBossCacheListenerAPIProposal", was updated Feb 22, 2010
by Manik Surtani.

To view the document, visit:
http://community.jboss.org/docs/DOC-10269#cf

Document:
--------------------------------------------------------------
h2.  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
 
h3.  Recommended Changes
* Use annotations and remove interface requirements
* Put notification data in a class instead of parameters
* Use a common notification base class
 
h3.  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.
 
h3.  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
 
h2.  Examples
 
The following are example cases using the proposed API
 
h3.  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());
   }
}


 
h3.  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();   
      }

   }
}

h3.  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);
   }

}

 

--------------------------------------------------------------