

                             New TreeCache Listener
                             ======================



Author: Hany Mesha (hmesha@novell.com)
Revision: $Id: NewTreeCacheListener.txt 428 2005-08-22 20:48:25Z hmesha $

JIRA issues:
------------ 
1. http://jira.jboss.com/jira/browse/JBCACHE-87
2. http://jira.jboss.com/jira/browse/JBCACHE-159
3. http://jira.jboss.com/jira/browse/JBCACHE-229
4. http://jira.jboss.com/jira/browse/JBCACHE-261

Goal: 
-----

New event types are needed for added new features to JBossCache in 1.2.4 release 
and enhancements requests by users. Adding new event types to the current 
TreeCacheListener interface will break the current implementation forcing 
implementators to re-work their implementation. This document presents a solution 
to this problem in release 1.2.4 which will also serve as a long term startegy 
to be completed in release 1.3 to avoid such a problem in the future.

Design
------
1. Create ExtendedTreeCacheListener interface to include the new event types. Instead of following 
TreeCacheListener way of defining event types pre... and ...'ed, create action method cooresponds to 
node event with a boolean to indicate whether the notification should be issued before or after the action. 
The user would implement the event interested in by passing to the method the boolean vlaue.

Currently the following new events are needed for callbacks:
   a. Passivate/Activate (JBCACHE-229)
      1. nodeActivate(Fqn fqn, boolean pre)
      2. nodePassivate(Fqn fqn, boolean pre)
   b. Evict and Remove (JBCACHE-159)
      1. nodeEvict(Fqn fqn, boolean pre)  // post should not be implemented at this point since nodEvicted 
                                          // already exist in TreeCacheListener, refactoring will be needed 
                                          // in release 1.3
      2. nodeRemove(Fqn fqn, boolean pre) // post should not be implemented at this point since nodRemoved 
                                          // already exist in TreeCacheListener, refactoring will be needed 
                                          // in release 1.3
   c. (JBCACHE-261)??
   
Note: ExtendedTreeCacheListener will be used to include new events in 1.2.4 and 1.2.5. In 1.3,  
it will be merged with TreeCacheListener. The nature of this merge is out of the scope of this effort.
 
2. Create AbstractTreeCacheListener implements TreeCacheListener and ExtendedTreeCacheListener (JBCACHE-87). 
The abstract class will allow the integration of the new events and any future events to be added into 
existing classes without interruption. Also, classes that are not interested in the event can simply 
ignore it. Refactoring is needed to extend the abstract class instead of implementing the listeners directly.

Classes that need refactoring: Only classes that need to implement any of the new event types.

3. Create Notification Interceptor and add it to the bottom of the interceptor stack on cache startup. 
This interceptor will assume the responsibility of notification on behalf of all the interceptors in 
the stack. Therefore, the other interceptors will not worry about notifications. 
The notification interceptor will simply invoke TreeCache callback implemented methods. If "pre=true",  
on the way in pre-notification is issued for the particular method call. If "pre=false", on the way out to 
invokes the notification.

Issues:
-------

1. JBCACHE-48, JBCACHE-49 are not relevant to this effort, is the assumption true here?
2. JBCACHE-261 requirements are not clear with respect to this effort. 
Note: Based on the discussion we had during our meeting, Bela added to JGroups 2.2.9 
"payload" in MethodCall put and get methods.

