org.jboss.cache.loader
Class ChainingCacheLoader

java.lang.Object
  org.jboss.cache.loader.ChainingCacheLoader

All Implemented Interfaces:

CacheLoader, ExtendedCacheLoader, org.jboss.system.Service

public class ChainingCacheLoader
extends java.lang.Object
implements ExtendedCacheLoader

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@jboss.org)

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(java.lang.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
java.util.Map	get(Fqn name) Returns all keys and values from the persistent store, given a fully qualified name
java.util.List	getCacheLoaders() Returns a List of individual cache loaders configured.
java.util.Set	getChildrenNames(Fqn fqn) Returns a list of children names, all names are relative.
int	getSize() Returns the number of cache loaders in the chain.
byte[]	loadEntireState() Fetch the entire state for this cache from secondary storage (disk, DB) and return it as a byte buffer.
byte[]	loadState(Fqn subtree) Fetch a portion of the state for this cache from secondary storage (disk, DB) and return it as a byte buffer.
void	prepare(java.lang.Object tx, java.util.List modifications, boolean one_phase) Prepare the modifications.
void	purgeIfNecessary()
void	put(Fqn name, java.util.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
java.lang.Object	put(Fqn name, java.lang.Object key, java.lang.Object value) Inserts key and value into the attributes hashmap of the given node.
void	put(java.util.List modifications) Inserts all modifications to the backend store.
void	remove(Fqn name) Removes the given node.
java.lang.Object	remove(Fqn name, java.lang.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(java.lang.Object tx) Roll the transaction back.
void	setCache(TreeCache c) This method allows the CacheLoader to set the TreeCache, therefore allowing the CacheLoader to invoke methods of the TreeCache.
void	setConfig(java.util.Properties url) Sets the configuration.
void	setRegionManager(RegionManager manager) No-op, as this class doesn't directly use the RegionManager.
void	start()
void	stop()
void	storeEntireState(byte[] state) Store the given state in secondary storage.
void	storeState(byte[] state, Fqn subtree) Store the given portion of the cache tree's state in secondary storage.
java.lang.String	toString()

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(java.util.Properties url)

Sets the configuration. Will be called before create() and start()

Specified by:

setConfig in interface CacheLoader

Parameters:

url - A list of properties, defined in the XML file

setCache

public void setCache(TreeCache c)

This method allows the CacheLoader to set the TreeCache, therefore allowing the CacheLoader to invoke methods of the TreeCache. It can also use the TreeCache to fetch configuration information. Alternatively, the CacheLoader could maintain its own configuration
This method will be called directly after the CacheLoader instance has been created

Specified by:

setCache in interface CacheLoader

Parameters:

c - The cache on which this loader works

getChildrenNames

public java.util.Set getChildrenNames(Fqn fqn)
                               throws java.lang.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

Specified by:

getChildrenNames in interface CacheLoader

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:

java.lang.Exception

get

public java.util.Map get(Fqn name)
                  throws java.lang.Exception

Returns all keys and values from the persistent store, given a fully qualified name

Specified by:

get in interface CacheLoader

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:

java.lang.Exception

exists

public boolean exists(Fqn name)
               throws java.lang.Exception

Checks whether the CacheLoader has a node with Fqn

Specified by:

exists in interface CacheLoader

Parameters:

name -

Returns:

True if node exists, false otherwise

Throws:

java.lang.Exception

put

public java.lang.Object put(Fqn name,
                            java.lang.Object key,
                            java.lang.Object value)
                     throws java.lang.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

Specified by:

put in interface CacheLoader

Throws:

java.lang.Exception

put

public void put(Fqn name,
                java.util.Map attributes)
         throws java.lang.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

Specified by:

put in interface CacheLoader

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 modifications)
         throws java.lang.Exception

Inserts all modifications to the backend store. Overwrite whatever is already in the datastore.

Specified by:

put in interface CacheLoader

Parameters:

modifications - A List of modifications

Throws:

java.lang.Exception

remove

public java.lang.Object remove(Fqn name,
                               java.lang.Object key)
                        throws java.lang.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.

Specified by:

remove in interface CacheLoader

Throws:

java.lang.Exception

remove

public void remove(Fqn name)
            throws java.lang.Exception

Removes the given node. If the node is the root of a subtree, this will recursively remove all subnodes, depth-first

Specified by:

remove in interface CacheLoader

Throws:

java.lang.Exception

removeData

public void removeData(Fqn name)
                throws java.lang.Exception

Removes all attributes from a given node, but doesn't delete the node itself

Specified by:

removeData in interface CacheLoader

Parameters:

name -

Throws:

java.lang.Exception

prepare

public void prepare(java.lang.Object tx,
                    java.util.List modifications,
                    boolean one_phase)
             throws java.lang.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

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:

java.lang.Exception

commit

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

Parameters:

tx -

Throws:

java.lang.Exception

rollback

public void rollback(java.lang.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

Parameters:

tx -

loadEntireState

public byte[] loadEntireState()
                       throws java.lang.Exception

Fetch the entire state for this cache from secondary storage (disk, DB) and return it as a byte buffer. This is for initialization of a new cache from a remote cache. The new cache would then call storeEntireState().
Only fetches state from the loader with fetchPersistentState as true. todo: define binary format for exchanging state

Specified by:

loadEntireState in interface CacheLoader

Throws:

java.lang.Exception

storeEntireState

public void storeEntireState(byte[] state)
                      throws java.lang.Exception

Store the given state in secondary storage. Overwrite whatever is currently in secondary storage. Only stores this state in a loader that has fetchPersistentState as true.

Specified by:

storeEntireState in interface CacheLoader

Throws:

java.lang.Exception

create

public void create()
            throws java.lang.Exception

Creates individual cache loaders.

Specified by:

create in interface org.jboss.system.Service

Throws:

java.lang.Exception

start

public void start()
           throws java.lang.Exception

Specified by:

start in interface org.jboss.system.Service

Throws:

java.lang.Exception

stop

public void stop()

Specified by:

stop in interface org.jboss.system.Service

destroy

public void destroy()

Specified by:

destroy in interface org.jboss.system.Service

loadState

public byte[] loadState(Fqn subtree)
                 throws java.lang.Exception

Description copied from interface: ExtendedCacheLoader

Fetch a portion of the state for this cache from secondary storage (disk, DB) and return it as a byte buffer. This is for activation of a portion of new cache from a remote cache. The new cache would then call ExtendedCacheLoader.storeState(byte[], Fqn).

Specified by:

loadState in interface ExtendedCacheLoader

Parameters:

subtree - Fqn naming the root (i.e. highest level parent) node of the subtree for which state is requested.

Throws:

java.lang.Exception

See Also:

TreeCache.activateRegion(String)

setRegionManager

public void setRegionManager(RegionManager manager)

No-op, as this class doesn't directly use the RegionManager.

Specified by:

setRegionManager in interface ExtendedCacheLoader

Parameters:

manager - the region manager to use, or null.

storeState

public void storeState(byte[] state,
                       Fqn subtree)
                throws java.lang.Exception

Description copied from interface: ExtendedCacheLoader

Store 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"

Specified by:

storeState in interface ExtendedCacheLoader

Parameters:

state - the state to store

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.

Throws:

java.lang.Exception

getSize

public int getSize()

Returns the number of cache loaders in the chain.

getCacheLoaders

public java.util.List 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 java.lang.String toString()

Overrides:

toString in class java.lang.Object

purgeIfNecessary

public void purgeIfNecessary()
                      throws java.lang.Exception

Throws:

java.lang.Exception