org.jboss.cache.loader
Class SingletonStoreCacheLoader

java.lang.Object
  org.jboss.cache.loader.AbstractCacheLoader
      org.jboss.cache.loader.AbstractDelegatingCacheLoader
          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

buddyFqnTransformer, 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(Future future, int timeout, TimeUnit unit) Method that waits for the in-memory to cache loader state to finish.
void	commit(Object tx) Calls the underlying cache loader's operation if the current node is the coordinator.
void	create() Lifecycle method, called when the cache loader is created.
protected Callable<?>	createPushStateTask() Factory method for the creation of a Callable task in charge of pushing in-memory state to cache loader.
protected 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(Object tx, 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, Map attributes) Calls the underlying cache loader's operation if the current node is the coordinator.
Object	put(Fqn name, Object key, Object value) Calls the underlying cache loader's operation if the current node is the coordinator.
void	put(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.
Object	remove(Fqn fqn, 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(Object tx) Calls the underlying cache loader's operation if the current node is the coordinator.
void	setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config) Sets the config for SingletonStoreCacheLoader and for the delegating cache loader.
void	storeEntireState(ObjectInputStream is) Calls the underlying cache loader's operation if the current node is the coordinator.
void	storeState(Fqn subtree, ObjectInputStream is) Calls the underlying cache loader's operation if the current node is the coordinator.
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

destroy, exists, get, getCacheLoader, getConfig, getChildrenNames, loadEntireState, loadState, setCache, setCacheLoader, setRegionManager, start, stop

Methods inherited from class org.jboss.cache.loader.AbstractCacheLoader

doMarshall, doUnmarshall, getMarshaller, getNodeDataList, loadStateHelper, move, put, regionAwareMarshall, regionAwareUnmarshall, storeStateHelper

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:

config - 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 PluggableConfigurationComponent.getProperties() method to find configuration information. Alternatively, may be a type-specific subclass of CacheLoaderConfig.IndividualCacheLoaderConfig, if there is one.

create

public void create()
            throws Exception

Description copied from interface: CacheLoader

Lifecycle method, called when the cache loader is created.

Specified by:

create in interface CacheLoader

Overrides:

create in class AbstractDelegatingCacheLoader

Throws:

Exception

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 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 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 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:

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(Future future,
                                    int timeout,
                                    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 Object put(Fqn name,
                  Object key,
                  Object value)
           throws 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:

Exception

put

public void put(Fqn name,
                Map attributes)
         throws 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:

Exception

put

public void put(List<Modification> modifications)
         throws 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:

Exception

remove

public Object remove(Fqn fqn,
                     Object key)
              throws 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:

Exception

remove

public void remove(Fqn fqn)
            throws 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:

Exception

removeData

public void removeData(Fqn fqn)
                throws 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:

Exception

prepare

public void prepare(Object tx,
                    List<Modification> modifications,
                    boolean one_phase)
             throws 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:

Exception

commit

public void commit(Object tx)
            throws 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:

Exception

rollback

public void rollback(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(ObjectInputStream is)
                      throws 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:

Exception

See Also:

AbstractCacheLoader.storeEntireState(ObjectInputStream), NodeData

storeState

public void storeState(Fqn subtree,
                       ObjectInputStream is)
                throws 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:

Exception

See Also:

AbstractCacheLoader.storeState(Fqn,ObjectInputStream), NodeData

toString

public String toString()

Calls the underlying cache loader's operation if the current node is the coordinator.

Overrides:

toString in class Object