Designing Habanero - TreeCacheListener and CacheLoader

[manik]

As a first in a series of discussions I'm about to kick off regarding API changes for JBoss Cache 2.0.0 (Habanero), I want to talk about some of the API interfaces, specifically the TreeCacheListener and CacheLoader interfaces.

The JIRA task for this is http://jira.jboss.com/jira/browse/JBCACHE-595

[manik]

Re: TreeCacheListener, I'd like to merge the TreeCacheListener and ExtendedTreeCacheListener into a single TreeCacheListener.

I'd also like to change some method signatures in the TreeCacheListener such that the combined TreeCacheListener would look like:

 void nodeCreated(Fqn fqn, Map data, boolean isLocal)

 void nodeRemoved(Fqn fqn, Map data, boolean pre, boolean isLocal)

 void nodeModified(Fqn fqn, Map originalData, Map newData, boolean pre, boolean isLocal)

 void nodeEvicted(Fqn fqn, boolean pre)

 void nodeActivated(Fqn fqn, boolean pre)

 void nodePassivated(Fqn fqn, boolean pre)

In addition, to facilitate JBCACHE-57 (using a cache interface rather than the TreeCache impl)

 void cacheStarted(Cache cache)

 void cacheStopped(Cache cache)

[manik]

Regarding CacheLoaders, I would just change all TreeCache params to the Cache interface. Is there a good reason to use the CacheSPI interface instead?

See related discussion http://www.jboss.com/index.html?module=bb&op=viewtopic&p=3940731#3940731

[manik]

On a less critical note, I also think we should rename TreeCacheListener to CacheListener (maintain consistency with what the world sees - a Cache interface - as well as JSR-107)

[belaban]

Re: TreeCacheListener, I'd like to merge the TreeCacheListener and ExtendedTreeCacheListener into a single TreeCacheListener.

I'd also like to change some method signatures in the TreeCacheListener such that the combined TreeCacheListener would look like:

 void nodeCreated(Fqn fqn, Map data, boolean isLocal)

 void nodeRemoved(Fqn fqn, Map data, boolean pre, boolean isLocal)

 void nodeModified(Fqn fqn, Map originalData, Map newData, boolean pre, boolean isLocal)

 void nodeEvicted(Fqn fqn, boolean pre)

 void nodeActivated(Fqn fqn, boolean pre)

 void nodePassivated(Fqn fqn, boolean pre)

In addition, to facilitate JBCACHE-57 (using a cache interface rather than the TreeCache impl)

 void cacheStarted(Cache cache)

 void cacheStopped(Cache cache)

+1 on CacheListener.

For all of the callbacks, we need proper definition of semantics, e.g. the do the Maps shipped with the callbacks contain copies of the data, or do they point back to the real map. If so, are they Collections.unmodifiable refs, or can we modify the data through the callbacks ?

[manik]

For all of the callbacks, we need proper definition of semantics, e.g. the do the Maps shipped with the callbacks contain copies of the data, or do they point back to the real map. If so, are they Collections.unmodifiable refs, or can we modify the data through the callbacks ?

Agreed. This needs to be documented correctly. I think it is sensible that it is simply a read-only version of the data - Collections.unmidifiable refs as you suggested. Listeners should not be allowed to modify ths data anyway - any mods should be new calls to the cache.

[ben.wang]

Now that we have buddy replication, should we add listening events for that as well? I think upper layer management code will be interested.

[manik]

What sort of events? Buddy group assignment events?

[ben.wang]

Maybe just one big even that contains the br assignment information within this cluster. Whenever br composition changes, this event is emitted.

[manik]

Well, BR assignments are triggered by viewChange events themselves - so everytime there is a view change there will be a buddyGroupReassignment event. The only difference is with the buddyGroupReassignment event we can pass in the new group membership.

Is this useful? I mean, in the end BR is just a form of replication and is fairly specific in terms of use-case. Not all use cases will make use of it and is there much point in adding BR events into the listener which many use cases will implement and make use of?

[galder.zamarreno]

I agree with Manik, I can't think of a straightforward use-case for handling that event and so, I agree that should not be included it in CacheListener.

[ben.wang]

Well, the event will definitely be useful. It is just the question how we want to do it? E.g., be it in CacheListener or ManagementCacheListener. To me, this is management events but it is important. For example, how can an admin know the history of the buddy group membership and also the current one?

[brian.stansberry]

When we merge CacheLoader and ExtendedCacheLoader, we need to ensure that storeState(byte[], Fqn) specifies that implementations have the ability to integrate state from the main tree into a different subtree (e.g. a buddy backup subtree). See
http://www.jboss.com/index.html?module=bb&op=viewtopic&t=82416 for explanation.

[brian.stansberry]

Just noticed that CacheLoader extends org.jboss.system.Service. We should look at just adding the methods directly to CacheLoader and removing that tie to the jboss-system.jar.

[manik]

I've got a preliminary set of interfaces available. Pls have a look at http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHabanero, which is the landing page for this new design. There are links to sample javadocs of the interfaces I have put together.

I'll put up UML diagrams there very shortly too.

For the time being, I haven't updated the CacheLoader interface - just the CacheListener one.

One of the things I want to discuss is whether we need a separate ClusterListener interface as well, with callbacks relating to buddy group reorganisation, view changes, etc.