org.jboss.cache.loader
Class SingletonStoreCacheLoader

java.lang.Object
  extended by org.jboss.cache.loader.AbstractCacheLoader
      extended by org.jboss.cache.loader.AbstractDelegatingCacheLoader
          extended by org.jboss.cache.loader.SingletonStoreCacheLoader
All Implemented Interfaces:
CacheLoader

public class SingletonStoreCacheLoader
extends AbstractDelegatingCacheLoader

SingletonStoreCacheLoader is a delegating cache loader used for situations when only one node should interact with the underlying store. The coordinator of the cluster will be responsible for the underlying CacheLoader. SingletonStoreCacheLoader is a simply facade to a real CacheLoader implementation. It always delegates reads to the real CacheLoader.

Writes are forwarded only if this SingletonStoreCacheLoader is currently the cordinator. This avoid having all CacheLoaders in a cluster writing the same data to the same underlying store. Although not incorrect (e.g. a DB will just discard additional INSERTs for the same key, and throw an exception), this will avoid a lot of redundant work.

Whenever the current coordinator dies (or leaves), the second in line will take over. That SingletonStoreCacheLoader will then pass writes through to its underlying CacheLoader. Optionally, when a new coordinator takes over the Singleton, it can push the in-memory state to the cache cacheLoader, within a time constraint.

Author:
Bela Ban, Galder Zamarreno

Nested Class Summary
static class SingletonStoreCacheLoader.PushStateException
          Exception representing any issues that arise from pushing the in-memory state to the cache loader.
 class SingletonStoreCacheLoader.SingletonStoreListener
          Cache listener that reacts to cluster topology changes to find out whether a new coordinator is elected.
 
Field Summary
 
Fields inherited from class org.jboss.cache.loader.AbstractCacheLoader
cache, regionManager, transactions
 
Constructor Summary
  SingletonStoreCacheLoader()
          Empty constructor so that it can instantiated using reflection.
protected SingletonStoreCacheLoader(SingletonStoreDefaultConfig config)
          Protected constructor which should only be used from unit tests.
 
Method Summary
protected  void activeStatusChanged(boolean newActiveState)
          Method called when the node either becomes the coordinator or stops being the coordinator.
protected  void awaitForPushToFinish(java.util.concurrent.Future future, int timeout, java.util.concurrent.TimeUnit unit)
          Method that waits for the in-memory to cache loader state to finish.
 void commit(java.lang.Object tx)
          Calls the underlying cache loader's operation if the current node is the coordinator.
protected  java.util.concurrent.Callable<?> createPushStateTask()
          Factory method for the creation of a Callable task in charge of pushing in-memory state to cache loader.
protected  java.util.concurrent.Future<?> getPushStateFuture()
          Returns the Future instance of a running in-memory to cache loader push task.
protected  SingletonStoreDefaultConfig getSingletonStoreDefaultConfig()
          Returns SingletonStoreCacheLoader's configuration instance.
 void prepare(java.lang.Object tx, java.util.List<Modification> modifications, boolean one_phase)
          Calls the underlying cache loader's operation if the current node is the coordinator.
protected  void pushState(NodeSPI node)
          Pushes the state of a specific node by reading the node's data from the cache and putting in the cache store via the cache loader.
 void put(Fqn name, java.util.Map attributes)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 java.lang.Object put(Fqn name, java.lang.Object key, java.lang.Object value)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 void put(java.util.List<Modification> modifications)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 void remove(Fqn fqn)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 java.lang.Object remove(Fqn fqn, java.lang.Object key)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 void removeData(Fqn fqn)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 void rollback(java.lang.Object tx)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 void setCache(CacheSPI c)
          Sets the cache loader's CacheSPI reference and also adds a listener to the cache that reacts to cluster topology changes.
 void setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config)
          Sets the config for SingletonStoreCacheLoader and for the delegating cache loader.
 void storeEntireState(java.io.ObjectInputStream is)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 void storeState(Fqn subtree, java.io.ObjectInputStream is)
          Calls the underlying cache loader's operation if the current node is the coordinator.
 java.lang.String toString()
          Calls the underlying cache loader's operation if the current node is the coordinator.
 
Methods inherited from class org.jboss.cache.loader.AbstractDelegatingCacheLoader
create, destroy, exists, get, getCacheLoader, getChildrenNames, getConfig, loadEntireState, loadState, setCacheLoader, setRegionManager, start, stop
 
Methods inherited from class org.jboss.cache.loader.AbstractCacheLoader
getMarshaller, getNodeDataList, loadStateHelper, put
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SingletonStoreCacheLoader

public SingletonStoreCacheLoader()
Empty constructor so that it can instantiated using reflection.


SingletonStoreCacheLoader

protected SingletonStoreCacheLoader(SingletonStoreDefaultConfig config)
Protected constructor which should only be used from unit tests. Production code should set pushStateWhenCoordinator using setConfig() method instead.

Parameters:
SingletonStoreDefaultConfig - configuration instance for SingletonStoreCacheLoader
Method Detail

setConfig

public void setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config)
Sets the config for SingletonStoreCacheLoader and for the delegating cache loader.

Specified by:
setConfig in interface CacheLoader
Overrides:
setConfig in class AbstractDelegatingCacheLoader
Parameters:
config - May be an instance of the CacheLoaderConfig.IndividualCacheLoaderConfig base class, in which case the cache loader should use the CacheLoaderConfig.IndividualCacheLoaderConfig.getProperties() method to find configuration information. Alternatively, may be a type-specific subclass of CacheLoaderConfig.IndividualCacheLoaderConfig, if there is one.

setCache

public void setCache(CacheSPI c)
Sets the cache loader's CacheSPI reference and also adds a listener to the cache that reacts to cluster topology changes.

Specified by:
setCache in interface CacheLoader
Overrides:
setCache in class AbstractDelegatingCacheLoader
Parameters:
c - instance of CacheSPI

getSingletonStoreDefaultConfig

protected SingletonStoreDefaultConfig getSingletonStoreDefaultConfig()
Returns SingletonStoreCacheLoader's configuration instance. This method has been defined for convenience reasons when unit testing SingletonStoreCacheLoader's configuration.

Returns:
instance of SingletonStoreDefaultConfig

getPushStateFuture

protected java.util.concurrent.Future<?> getPushStateFuture()
Returns the Future instance of a running in-memory to cache loader push task. This method has been defined for convenience reasons when unit testing.

Returns:
an instance of Future

activeStatusChanged

protected void activeStatusChanged(boolean newActiveState)
                            throws SingletonStoreCacheLoader.PushStateException
Method called when the node either becomes the coordinator or stops being the coordinator. If it becomes the coordinator, it can optionally start the in-memory state transfer to the underlying cache store.

Parameters:
newActiveState - true if the node just became the coordinator, false if the nodes stopped being the coordinator.
Throws:
SingletonStoreCacheLoader.PushStateException

createPushStateTask

protected java.util.concurrent.Callable<?> createPushStateTask()
Factory method for the creation of a Callable task in charge of pushing in-memory state to cache loader.

Returns:
new instance of Callable whose call() method either throws an exception or returns null if the task was successfull.

pushState

protected void pushState(NodeSPI node)
                  throws java.lang.Exception
Pushes the state of a specific node by reading the node's data from the cache and putting in the cache store via the cache loader. This method is call recursively so that it iterates through the whole cache.

Parameters:
node - instance of NodeSPI to push to the cache loader
Throws:
java.lang.Exception - if there's any issues reading the data from the cache or pushing the node's data to the cache loader.

awaitForPushToFinish

protected void awaitForPushToFinish(java.util.concurrent.Future future,
                                    int timeout,
                                    java.util.concurrent.TimeUnit unit)
Method that waits for the in-memory to cache loader state to finish. This method's called in case a push state is already in progress and we need to wait for it to finish.

Parameters:
future - instance of Future representing the on going push task
timeout - time to wait for the push task to finish
unit - instance of TimeUnit representing the unit of timeout

put

public java.lang.Object put(Fqn name,
                            java.lang.Object key,
                            java.lang.Object value)
                     throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
put in interface CacheLoader
Overrides:
put in class AbstractDelegatingCacheLoader
Throws:
java.lang.Exception

put

public void put(Fqn name,
                java.util.Map attributes)
         throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
put in interface CacheLoader
Overrides:
put in class AbstractDelegatingCacheLoader
Parameters:
name - The fully qualified name of the node
attributes - A Map of attributes. Can be null
Throws:
java.lang.Exception

put

public void put(java.util.List<Modification> modifications)
         throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
put in interface CacheLoader
Overrides:
put in class AbstractDelegatingCacheLoader
Parameters:
modifications - A List of modifications
Throws:
java.lang.Exception

remove

public java.lang.Object remove(Fqn fqn,
                               java.lang.Object key)
                        throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
remove in interface CacheLoader
Overrides:
remove in class AbstractDelegatingCacheLoader
Throws:
java.lang.Exception

remove

public void remove(Fqn fqn)
            throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
remove in interface CacheLoader
Overrides:
remove in class AbstractDelegatingCacheLoader
Parameters:
fqn - the Fqn of the node
Throws:
java.lang.Exception

removeData

public void removeData(Fqn fqn)
                throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
removeData in interface CacheLoader
Overrides:
removeData in class AbstractDelegatingCacheLoader
Parameters:
fqn - the Fqn of the node
Throws:
java.lang.Exception

prepare

public void prepare(java.lang.Object tx,
                    java.util.List<Modification> modifications,
                    boolean one_phase)
             throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
prepare in interface CacheLoader
Overrides:
prepare in class AbstractDelegatingCacheLoader
Parameters:
tx - The transaction, indended to be used by implementations as an identifier of the transaction (and not necessarily a JTA Transaction object)
modifications - A List containing Modifications, for the given transaction
one_phase - Persist immediately and (for example) commit the local JDBC transaction as well. When true, we won't get a CacheLoader.commit(Object) or CacheLoader.rollback(Object) method call later
Throws:
java.lang.Exception

commit

public void commit(java.lang.Object tx)
            throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
commit in interface CacheLoader
Overrides:
commit in class AbstractDelegatingCacheLoader
Parameters:
tx - transaction to commit
Throws:
java.lang.Exception

rollback

public void rollback(java.lang.Object tx)
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
rollback in interface CacheLoader
Overrides:
rollback in class AbstractDelegatingCacheLoader
Parameters:
tx - transaction to roll back

storeEntireState

public void storeEntireState(java.io.ObjectInputStream is)
                      throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
storeEntireState in interface CacheLoader
Overrides:
storeEntireState in class AbstractDelegatingCacheLoader
Parameters:
is - ObjectInputStream to read state
Throws:
java.lang.Exception
See Also:
AbstractCacheLoader.storeEntireState(ObjectInputStream), NodeData

storeState

public void storeState(Fqn subtree,
                       java.io.ObjectInputStream is)
                throws java.lang.Exception
Calls the underlying cache loader's operation if the current node is the coordinator.

Specified by:
storeState in interface CacheLoader
Overrides:
storeState in class AbstractDelegatingCacheLoader
Parameters:
subtree - Fqn naming the root (i.e. highest level parent) node of the subtree included in state. If the Fqns of the data included in state are not already children of subtree, then their Fqns should be altered to make them children of subtree before they are persisted.
is - ObjectInputStream to read state
Throws:
java.lang.Exception
See Also:
AbstractCacheLoader.storeState(Fqn,ObjectInputStream), NodeData

toString

public java.lang.String toString()
Calls the underlying cache loader's operation if the current node is the coordinator.

Overrides:
toString in class java.lang.Object