ehcache

net.sf.ehcache.distribution
Class RMIAsynchronousCacheReplicator

java.lang.Object
  extended by net.sf.ehcache.distribution.RMISynchronousCacheReplicator
      extended by net.sf.ehcache.distribution.RMIAsynchronousCacheReplicator
All Implemented Interfaces:
CacheReplicator, CacheEventListener

public final class RMIAsynchronousCacheReplicator
extends RMISynchronousCacheReplicator

Listens to CacheManager and Cache events and propagates those to CachePeer peers of the Cache asynchronously.

Updates are guaranteed to be replicated in the order in which they are received.

While much faster in operation than RMISynchronousCacheReplicator, it does suffer from a number of problems. Elements, which may be being spooled to DiskStore may stay around in memory because references are being held to them from EventMessages which are queued up. The replication thread runs once per second, limiting the build up. However a lot of elements can be put into a cache in that time. We do not want to get an OutOfMemoryError using distribution in circumstances when it would not happen if we were just using the DiskStore.

Accordingly, EventMessages are held by SoftReference in the queue, so that they can be discarded if required by the GC to avoid an OutOfMemoryError. A log message will be issued on each flush of the queue if there were any forced discards. One problem with GC collection of SoftReferences is that the VM (JDK1.5 anyway) will do that rather than grow the heap size to the maximum. The workaround is to either set minimum heap size to the maximum heap size to force heap allocation at start up, or put up with a few lost messages while the heap grows.

Version:
$Id: RMIAsynchronousCacheReplicator.java 141 2006-06-30 01:56:32Z gregluck $
Author:
Greg Luck

Field Summary
protected static int REPLICATION_THREAD_INTERVAL
          The amount of time the replication thread sleeps after it detects the replicationQueue is empty before checking again.
protected  java.util.List replicationQueue
          A queue of updates.
protected  java.lang.Thread replicationThread
          A thread which handles replication, so that replication can take place asynchronously and not hold up the cache
 
Fields inherited from class net.sf.ehcache.distribution.RMISynchronousCacheReplicator
replicatePuts, replicateRemovals, replicateUpdates, replicateUpdatesViaCopy, status
 
Constructor Summary
protected RMIAsynchronousCacheReplicator(boolean replicatePuts, boolean replicateUpdates, boolean replicateUpdatesViaCopy, boolean replicateRemovals)
          Constructor for internal and subclass use
 
Method Summary
protected  void addToReplicationQueue(net.sf.ehcache.distribution.RMIAsynchronousCacheReplicator.CacheEventMessage cacheEventMessage)
          Adds a message to the queue.
 void dispose()
          Give the replicator a chance to cleanup and free resources when no longer needed
 void notifyElementPut(Cache cache, Element element)
          Called immediately after an element has been put into the cache.
 void notifyElementRemoved(Cache cache, Element element)
          Called immediately after an element has been removed.
 void notifyElementUpdated(Cache cache, Element element)
          Called immediately after an element has been put into the cache and the element already existed in the cache.
 
Methods inherited from class net.sf.ehcache.distribution.RMISynchronousCacheReplicator
alive, isReplicateUpdatesViaCopy, listRemoteCachePeers, notAlive, notifyElementExpired
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REPLICATION_THREAD_INTERVAL

protected static final int REPLICATION_THREAD_INTERVAL
The amount of time the replication thread sleeps after it detects the replicationQueue is empty before checking again.

See Also:
Constant Field Values

replicationThread

protected final java.lang.Thread replicationThread
A thread which handles replication, so that replication can take place asynchronously and not hold up the cache


replicationQueue

protected final java.util.List replicationQueue
A queue of updates.

Constructor Detail

RMIAsynchronousCacheReplicator

protected RMIAsynchronousCacheReplicator(boolean replicatePuts,
                                         boolean replicateUpdates,
                                         boolean replicateUpdatesViaCopy,
                                         boolean replicateRemovals)
Constructor for internal and subclass use

Parameters:
replicatePuts -
replicateUpdates -
replicateUpdatesViaCopy -
replicateRemovals -
Method Detail

notifyElementPut

public final void notifyElementPut(Cache cache,
                                   Element element)
                            throws CacheException
Called immediately after an element has been put into the cache. The Cache.put(net.sf.ehcache.Element) method will block until this method returns.

Implementers may wish to have access to the Element's fields, including value, so the element is provided. Implementers should be careful not to modify the element. The effect of any modifications is undefined.

This implementation queues the put notification for in-order replication to peers.

Specified by:
notifyElementPut in interface CacheEventListener
Overrides:
notifyElementPut in class RMISynchronousCacheReplicator
Parameters:
cache - the cache emitting the notification
element - the element which was just put into the cache.
Throws:
CacheException

notifyElementUpdated

public final void notifyElementUpdated(Cache cache,
                                       Element element)
                                throws CacheException
Called immediately after an element has been put into the cache and the element already existed in the cache. This is thus an update.

The Cache.put(net.sf.ehcache.Element) method will block until this method returns.

Implementers may wish to have access to the Element's fields, including value, so the element is provided. Implementers should be careful not to modify the element. The effect of any modifications is undefined.

Specified by:
notifyElementUpdated in interface CacheEventListener
Overrides:
notifyElementUpdated in class RMISynchronousCacheReplicator
Parameters:
cache - the cache emitting the notification
element - the element which was just put into the cache.
Throws:
CacheException

notifyElementRemoved

public final void notifyElementRemoved(Cache cache,
                                       Element element)
                                throws CacheException
Called immediately after an element has been removed. The remove method will block until this method returns.

This implementation queues the removal notification for in order replication to peers.

Specified by:
notifyElementRemoved in interface CacheEventListener
Overrides:
notifyElementRemoved in class RMISynchronousCacheReplicator
Parameters:
cache - the cache emitting the notification
element - just deleted
Throws:
CacheException

addToReplicationQueue

protected void addToReplicationQueue(net.sf.ehcache.distribution.RMIAsynchronousCacheReplicator.CacheEventMessage cacheEventMessage)
Adds a message to the queue.

This method checks the state of the replication thread and warns if it has stopped and then discards the message.

Parameters:
cacheEventMessage -

dispose

public final void dispose()
Give the replicator a chance to cleanup and free resources when no longer needed

Specified by:
dispose in interface CacheEventListener
Overrides:
dispose in class RMISynchronousCacheReplicator

ehcache