org.jboss.cache.loader
Class ChainingCacheLoader

java.lang.Object
  extended by org.jboss.cache.loader.AbstractCacheLoader
      extended by org.jboss.cache.loader.ChainingCacheLoader
All Implemented Interfaces:
Lifecycle, CacheLoader

public class ChainingCacheLoader
extends AbstractCacheLoader

This decorator is used whenever more than one cache loader is configured. READ operations are directed to each of the cache loaders (in the order which they were configured) until a non-null (or non-empty in the case of retrieving collection objects) result is achieved.

WRITE operations are propagated to ALL registered cacheloaders that specified set ignoreModifications to false.

Author:
Manik Surtani (manik AT jboss DOT org)

Field Summary
 
Fields inherited from class org.jboss.cache.loader.AbstractCacheLoader
buddyFqnTransformer, cache, regionManager, transactions
 
Constructor Summary
ChainingCacheLoader()
           
 
Method Summary
 void addCacheLoader(CacheLoader l, CacheLoaderConfig.IndividualCacheLoaderConfig cfg)
          Adds a cache loader to the chain (always added at the end of the chain)
 void commit(Object tx)
          Commit the transaction.
 void create()
          Creates individual cache loaders.
 void destroy()
           
 boolean exists(Fqn name)
          Checks whether the CacheLoader has a node with Fqn
 Map get(Fqn name)
          Returns all keys and values from the persistent store, given a fully qualified name
 List<CacheLoader> getCacheLoaders()
          Returns a List of individual cache loaders configured.
 Set<?> getChildrenNames(Fqn fqn)
          Returns a list of children names, all names are relative.
 CacheLoaderConfig.IndividualCacheLoaderConfig getConfig()
          Gets the configuration.
 int getSize()
          Returns the number of cache loaders in the chain.
 void injectDependencies(ComponentRegistry registry)
           
 void loadEntireState(ObjectOutputStream os)
          Fetches the entire state for this cache from secondary storage (disk, database) and writes it to a provided ObjectOutputStream.
 void loadState(Fqn subtree, ObjectOutputStream os)
          Fetches a portion of the state for this cache from secondary storage (disk, database) and writes it to a provided ObjectOutputStream.
 void prepare(Object tx, List modifications, boolean one_phase)
          Prepare the modifications.
 void purgeIfNecessary()
           
 void put(Fqn name, Map attributes)
          Inserts all elements of attributes into the attributes hashmap of the given node, overwriting existing attributes, but not clearing the existing hashmap before insertion (making it a union of existing and new attributes) If the node does not exist, all parent nodes from the root down are created automatically
 Object put(Fqn name, Object key, Object value)
          Inserts key and value into the attributes hashmap of the given node.
 void put(List<Modification> modifications)
          Inserts all modifications to the backend store.
 void remove(Fqn name)
          Removes the given node.
 Object remove(Fqn name, Object key)
          Removes the given key and value from the attributes of the given node.
 void removeData(Fqn name)
          Removes all attributes from a given node, but doesn't delete the node itself
 void rollback(Object tx)
          Roll the transaction back.
 void setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config)
          Sets the configuration.
 void setRegionManager(RegionManager manager)
          No-op, as this class doesn't directly use the ERegionManager.
 void start()
           
 void stop()
           
 void storeEntireState(ObjectInputStream is)
          Stores the entire state for this cache by reading it from a provided ObjectInputStream.
 void storeState(Fqn subtree, ObjectInputStream is)
          Stores the given portion of the cache tree's state in secondary storage.
 String toString()
           
 
Methods inherited from class org.jboss.cache.loader.AbstractCacheLoader
doMarshall, doUnmarshall, getMarshaller, getNodeDataList, loadStateHelper, move, put, regionAwareMarshall, regionAwareUnmarshall, setCache, storeStateHelper
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ChainingCacheLoader

public ChainingCacheLoader()
Method Detail

setConfig

public void setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config)
Sets the configuration. Will be called before create() and start()

Parameters:
config - ignored

getConfig

public CacheLoaderConfig.IndividualCacheLoaderConfig getConfig()
Description copied from interface: CacheLoader
Gets the configuration.

Returns:
the configuration, represented by a CacheLoaderConfig.IndividualCacheLoaderConfig object.

injectDependencies

public void injectDependencies(ComponentRegistry registry)

getChildrenNames

public Set<?> getChildrenNames(Fqn fqn)
                        throws Exception
Returns a list of children names, all names are relative. Returns null if the parent node is not found. The returned set must not be modified, e.g. use Collections.unmodifiableSet(s) to return the result

Parameters:
fqn - The FQN of the parent
Returns:
Set. A list of children. Returns null if no children nodes are present, or the parent is not present
Throws:
Exception

get

public Map get(Fqn name)
        throws Exception
Returns all keys and values from the persistent store, given a fully qualified name

Parameters:
name -
Returns:
Map of keys and values for the given node. Returns null if the node was not found, or if the node has no attributes
Throws:
Exception

exists

public boolean exists(Fqn name)
               throws Exception
Checks whether the CacheLoader has a node with Fqn

Parameters:
name -
Returns:
True if node exists, false otherwise
Throws:
Exception

put

public Object put(Fqn name,
                  Object key,
                  Object value)
           throws Exception
Inserts key and value into the attributes hashmap of the given node. If the node does not exist, all parent nodes from the root down are created automatically. Returns the old value

Throws:
Exception

put

public void put(Fqn name,
                Map attributes)
         throws Exception
Inserts all elements of attributes into the attributes hashmap of the given node, overwriting existing attributes, but not clearing the existing hashmap before insertion (making it a union of existing and new attributes) If the node does not exist, all parent nodes from the root down are created automatically

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
Inserts all modifications to the backend store. Overwrite whatever is already in the datastore.

Specified by:
put in interface CacheLoader
Overrides:
put in class AbstractCacheLoader
Parameters:
modifications - A List of modifications
Throws:
Exception

remove

public Object remove(Fqn name,
                     Object key)
              throws Exception
Removes the given key and value from the attributes of the given node. No-op if node doesn't exist. Returns the first response from the loader chain.

Throws:
Exception

remove

public void remove(Fqn name)
            throws Exception
Removes the given node. If the node is the root of a subtree, this will recursively remove all subnodes, depth-first

Parameters:
name - the Fqn of the node
Throws:
Exception

removeData

public void removeData(Fqn name)
                throws Exception
Removes all attributes from a given node, but doesn't delete the node itself

Parameters:
name -
Throws:
Exception

prepare

public void prepare(Object tx,
                    List modifications,
                    boolean one_phase)
             throws Exception
Prepare the modifications. For example, for a DB-based CacheLoader:
  1. Create a local (JDBC) transaction
  2. Associate the local transaction with tx (tx is the key)
  3. Execute the coresponding SQL statements against the DB (statements derived from modifications)
For non-transactional CacheLoader (e.g. file-based), this could be a null operation

Specified by:
prepare in interface CacheLoader
Overrides:
prepare in class AbstractCacheLoader
Parameters:
tx - The transaction, just used as a hashmap key
modifications - List, a list of all modifications within the given transaction
one_phase - Persist immediately and (for example) commit the local JDBC transaction as well. When true, we won't get a commit(Object) or rollback(Object) method call later
Throws:
Exception

commit

public void commit(Object tx)
            throws Exception
Commit the transaction. A DB-based CacheLoader would look up the local JDBC transaction asociated with tx and commit that transaction
Non-transactional CacheLoaders could simply write the data that was previously saved transiently under the given tx key, to (for example) a file system (note this only holds if the previous prepare() did not define one_phase=true

Specified by:
commit in interface CacheLoader
Overrides:
commit in class AbstractCacheLoader
Parameters:
tx -
Throws:
Exception

rollback

public void rollback(Object tx)
Roll the transaction back. A DB-based CacheLoader would look up the local JDBC transaction asociated with tx and roll back that transaction

Specified by:
rollback in interface CacheLoader
Overrides:
rollback in class AbstractCacheLoader
Parameters:
tx -

create

public void create()
            throws Exception
Creates individual cache loaders.

Specified by:
create in interface Lifecycle
Overrides:
create in class AbstractCacheLoader
Throws:
Exception

start

public void start()
           throws Exception
Specified by:
start in interface Lifecycle
Overrides:
start in class AbstractCacheLoader
Throws:
Exception

stop

public void stop()
Specified by:
stop in interface Lifecycle
Overrides:
stop in class AbstractCacheLoader

destroy

public void destroy()
Specified by:
destroy in interface Lifecycle
Overrides:
destroy in class AbstractCacheLoader

setRegionManager

public void setRegionManager(RegionManager manager)
No-op, as this class doesn't directly use the ERegionManager.

Specified by:
setRegionManager in interface CacheLoader
Overrides:
setRegionManager in class AbstractCacheLoader
Parameters:
manager - the region manager to use, or null.

loadEntireState

public void loadEntireState(ObjectOutputStream os)
                     throws Exception
Description copied from interface: CacheLoader
Fetches the entire state for this cache from secondary storage (disk, database) and writes it to a provided ObjectOutputStream. State written to the provided ObjectOutputStream parameter is used for initialization of a new CacheImpl instance. When the state gets transferred to the new cache instance its cacheloader calls CacheLoader.storeEntireState(ObjectInputStream)

Implementations of this method should not catch any exception or close the given ObjectOutputStream parameter. In order to ensure cacheloader interoperability contents of the cache are written to the ObjectOutputStream as a sequence of NodeData objects.

Default implementation is provided by AbstractCacheLoader and ensures cacheloader interoperability. Implementors are encouraged to consider extending AbstractCacheLoader prior to implementing completely custom cacheloader.

Specified by:
loadEntireState in interface CacheLoader
Overrides:
loadEntireState in class AbstractCacheLoader
Parameters:
os - ObjectOutputStream to write state
Throws:
Exception
See Also:
AbstractCacheLoader.loadEntireState(ObjectOutputStream), NodeData

loadState

public void loadState(Fqn subtree,
                      ObjectOutputStream os)
               throws Exception
Description copied from interface: CacheLoader
Fetches a portion of the state for this cache from secondary storage (disk, database) and writes it to a provided ObjectOutputStream. State written to the provided ObjectOutputStream parameter is used for activation of a portion of a new CacheImpl instance. When the state gets transferred to the new cache instance its cacheloader calls CacheLoader.storeState(Fqn,ObjectInputStream).

Implementations of this method should not catch any exception or close the given ObjectOutputStream parameter. In order to ensure cacheloader interoperability contents of the cache are written to the ObjectOutputStream as a sequence of NodeData objects.

Default implementation is provided by AbstractCacheLoader and ensures cacheloader interoperability. Implementors are encouraged to consider extending AbstractCacheLoader prior to implementing completely custom cacheloader.

Specified by:
loadState in interface CacheLoader
Overrides:
loadState in class AbstractCacheLoader
Parameters:
subtree - Fqn naming the root (i.e. highest level parent) node of the subtree for which state is requested.
os - ObjectOutputStream to write state
Throws:
Exception
See Also:
AbstractCacheLoader.loadState(Fqn,ObjectOutputStream), Region.activate(), NodeData

storeEntireState

public void storeEntireState(ObjectInputStream is)
                      throws Exception
Description copied from interface: CacheLoader
Stores the entire state for this cache by reading it from a provided ObjectInputStream. The state was provided to this cache by calling CacheLoader.loadEntireState(ObjectOutputStream)} on some other cache instance. State currently in storage gets overwritten.

Implementations of this method should not catch any exception or close the given ObjectInputStream parameter. In order to ensure cacheloader interoperability contents of the cache are read from the ObjectInputStream as a sequence of NodeData objects.

Default implementation is provided by AbstractCacheLoader and ensures cacheloader interoperability. Implementors are encouraged to consider extending AbstractCacheLoader prior to implementing completely custom cacheloader.

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

storeState

public void storeState(Fqn subtree,
                       ObjectInputStream is)
                throws Exception
Description copied from interface: CacheLoader
Stores the given portion of the cache tree's state in secondary storage. Overwrite whatever is currently in secondary storage. If the transferred state has Fqns equal to or children of parameter subtree, then no special behavior is required. Otherwise, ensure that the state is integrated under the given subtree. Typically in the latter case subtree would be the Fqn of the buddy backup region for a buddy group; e.g.

If the the transferred state had Fqns starting with "/a" and subtree was "/_BUDDY_BACKUP_/192.168.1.2:5555" then the state should be stored in the local persistent store under "/_BUDDY_BACKUP_/192.168.1.2:5555/a"

Implementations of this method should not catch any exception or close the given ObjectInputStream parameter. In order to ensure cacheloader interoperability contents of the cache are read from the ObjectInputStream as a sequence of NodeData objects.

Default implementation is provided by AbstractCacheLoader and ensures cacheloader interoperability. Implementors are encouraged to consider extending AbstractCacheLoader prior to implementing completely custom cacheloader.

Specified by:
storeState in interface CacheLoader
Overrides:
storeState in class AbstractCacheLoader
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

getSize

public int getSize()
Returns the number of cache loaders in the chain.


getCacheLoaders

public List<CacheLoader> getCacheLoaders()
Returns a List of individual cache loaders configured.


addCacheLoader

public void addCacheLoader(CacheLoader l,
                           CacheLoaderConfig.IndividualCacheLoaderConfig cfg)
Adds a cache loader to the chain (always added at the end of the chain)

Parameters:
l - the cache loader to add
cfg - and its configuration

toString

public String toString()
Overrides:
toString in class Object

purgeIfNecessary

public void purgeIfNecessary()
                      throws Exception
Throws:
Exception


Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.