org.jboss.cache.loader
Interface CacheLoader

All Superinterfaces:

Lifecycle

All Known Subinterfaces:

CacheLoaderAop

All Known Implementing Classes:

AbstractCacheLoader, AbstractDelegatingCacheLoader, AdjListJDBCCacheLoader, AsyncCacheLoader, BdbjeCacheLoader, ChainingCacheLoader, ClusteredCacheLoader, FileCacheLoader, JDBCCacheLoader, JDBCCacheLoaderOld, JdbmCacheLoader, JdbmCacheLoader2, LocalDelegatingCacheLoader, ReadOnlyDelegatingCacheLoader, S3CacheLoader, SingletonStoreCacheLoader, TcpDelegatingCacheLoader

@ThreadSafe
public interface CacheLoader
extends Lifecycle

A CacheLoader implementation persists and load keys to and from secondary storage, such as a database or filesystem. Typically, implementations store a series of keys and values (an entire Map) under a single Fqn. Loading and saving properties of an entire Map should be atomic.

Lifecycle: First an instance of the loader is created, then the configuration (setConfig(org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig)) and cache (setCache(CacheSPI)) are set. After this, Lifecycle.create() is called. Then Lifecycle.start() is called. When re-deployed, Lifecycle.stop() will be called, followed by another Lifecycle.start(). Finally, when shut down, Lifecycle.destroy() is called, after which the loader is unusable.

An AbstractCacheLoader is provided as a convenient starting place when implementing your own CacheLoader.

It is important to note that all implementations are thread safe, as concurrent reads and writes, potentially even to the same Fqn, are possible.

Since:

2.0.0

Author:

Manik Surtani (manik AT jboss DOT org)

See Also:

CacheSPI, CacheLoaderConfig.IndividualCacheLoaderConfig, AbstractCacheLoader

Method Summary

void	commit(Object tx) Commits the transaction.
boolean	exists(Fqn name) Returns true if the CacheLoader has a node with a Fqn.
Map<Object,Object>	get(Fqn name) Returns all keys and values from the persistent store, given a Fqn
Set<?>	getChildrenNames(Fqn fqn) Returns a set of children node names.
CacheLoaderConfig.IndividualCacheLoaderConfig	getConfig() Gets the configuration.
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<Modification> modifications, boolean one_phase) Prepares a list of modifications.
void	put(Fqn name, Map<Object,Object> attributes) Puts all entries of the map into the existing map of the given node, overwriting existing keys, but not clearing the existing map before insertion.
Object	put(Fqn name, Object key, Object value) Puts a key and value into the attribute map of a given node.
void	put(List<Modification> modifications) Applies all modifications to the backend store.
void	remove(Fqn fqn) Removes the given node and all its subnodes, does nothing if the node does not exist.
Object	remove(Fqn fqn, Object key) Removes the given key and value from the attributes of the given node.
void	removeData(Fqn fqn) Removes all attributes from a given node, but doesn't delete the node itself or any subnodes.
void	rollback(Object tx) Rolls the transaction back.
void	setCache(CacheSPI c) Sets the CacheSPI that is maintaining this CacheLoader.
void	setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config) Sets the configuration.
void	setRegionManager(RegionManager manager) Sets the RegionManager this object should use to manage marshalling/unmarshalling of different regions using different classloaders.
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.

Methods inherited from interface org.jboss.cache.Lifecycle

create, destroy, start, stop

Method Detail

setConfig

void setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig config)

Sets the configuration. This is called before Lifecycle.create() and Lifecycle.start().

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.

getConfig

CacheLoaderConfig.IndividualCacheLoaderConfig getConfig()

Gets the configuration.

Returns:

the configuration, represented by a CacheLoaderConfig.IndividualCacheLoaderConfig object.

setCache

void setCache(CacheSPI c)

Sets the CacheSPI that is maintaining this CacheLoader. This method allows this CacheLoader to set a reference to the CacheSPI. This method is called be called after the CacheLoader instance has been constructed.

Parameters:

c - The cache on which this loader works

getChildrenNames

Set<?> getChildrenNames(Fqn fqn)
                        throws Exception

Returns a set of children node names. All names are relative to this parent Fqn. Returns null if the named node is not found or there are no children. The returned set must not be modifiable. Implementors can use Collections.unmodifiableSet(java.util.Set) to make the set unmodifiable.

Implementors may impose restrictions on the contents of an Fqn (such as Strings-only) and as such, indirectly impose the same restriction on the contents of a Set returned by getChildrenNames().

Parameters:

fqn - The Fqn of the parent

Returns:

Set a set of children. Returns null if no children nodes are present, or the parent is not present

Throws:

Exception

get

Map<Object,Object> get(Fqn name)
                       throws Exception

Returns all keys and values from the persistent store, given a Fqn

Parameters:

name - the Fqn to search for.

Returns:

Map keys and values for the given node. Returns null if the node is not found. If the node is found but has no attributes, this method returns an empty Map.

Throws:

Exception

exists

boolean exists(Fqn name)
               throws Exception

Returns true if the CacheLoader has a node with a Fqn.

Returns:

true if node exists, false otherwise

Throws:

Exception

put

Object put(Fqn name,
           Object key,
           Object value)
           throws Exception

Puts a key and value into the attribute map of a 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

void put(Fqn name,
         Map<Object,Object> attributes)
         throws Exception

Puts all entries of the map into the existing map of the given node, overwriting existing keys, but not clearing the existing map before insertion. This is the same behavior as Map.putAll(java.util.Map). If the node does not exist, all parent nodes from the root down are created automatically

Note since 3.0, as an optimization, this method will require a definitive attribute map and not just a subset. This will allow cache loader implementations to overwrite rather than merge, if that is deemed more efficient. This will not break backward compatibility since performing a merge will not cause any loss of data even though it is an unnecessary step.

Parameters:

name - The fully qualified name of the node

attributes - A Map of attributes. Can be null

Throws:

Exception

put

void put(List<Modification> modifications)
         throws Exception

Applies all modifications to the backend store. Changes may be applied in a single operation.

Parameters:

modifications - A List of modifications

Throws:

Exception

remove

Object remove(Fqn fqn,
              Object key)
              throws Exception

Removes the given key and value from the attributes of the given node. Does nothing if the node doesn't exist Returns the removed value.

Throws:

Exception

remove

void remove(Fqn fqn)
            throws Exception

Removes the given node and all its subnodes, does nothing if the node does not exist.

Parameters:

fqn - the Fqn of the node

Throws:

Exception

removeData

void removeData(Fqn fqn)
                throws Exception

Removes all attributes from a given node, but doesn't delete the node itself or any subnodes.

Parameters:

fqn - the Fqn of the node

Throws:

Exception

prepare

void prepare(Object tx,
             List<Modification> modifications,
             boolean one_phase)
             throws Exception

Prepares a list of 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 corresponding SQL statements against the DB (statements derived from modifications)

For non-transactional CacheLoader (e.g. file-based), the implementation could attempt to implement its own transactional logic, attempting to write data to a temp location (or memory) and writing it to the proper location upon commit.

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 commit(Object) or rollback(Object) method call later

Throws:

Exception

commit

void commit(Object tx)
            throws Exception

Commits 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

Parameters:

tx - transaction to commit

Throws:

Exception

rollback

void rollback(Object tx)

Rolls the transaction back. A DB-based CacheLoader would look up the local JDBC transaction asociated with tx and roll back that transaction.

Parameters:

tx - transaction to roll back

loadEntireState

void loadEntireState(ObjectOutputStream os)
                     throws Exception

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

Parameters:

os - ObjectOutputStream to write state

Throws:

Exception

See Also:

AbstractCacheLoader.loadEntireState(ObjectOutputStream), NodeData

storeEntireState

void storeEntireState(ObjectInputStream is)
                      throws Exception

Stores the entire state for this cache by reading it from a provided ObjectInputStream. The state was provided to this cache by calling 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.

Parameters:

is - ObjectInputStream to read state

Throws:

Exception

See Also:

AbstractCacheLoader.storeEntireState(ObjectInputStream), NodeData

loadState

void loadState(Fqn subtree,
               ObjectOutputStream os)
               throws Exception

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

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

storeState

void storeState(Fqn subtree,
                ObjectInputStream is)
                throws Exception

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.

Parameters:

is - ObjectInputStream to read state

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:

Exception

See Also:

AbstractCacheLoader.storeState(Fqn,ObjectInputStream), NodeData

setRegionManager

void setRegionManager(RegionManager manager)

Sets the RegionManager this object should use to manage marshalling/unmarshalling of different regions using different classloaders.

NOTE: This method is only intended to be used by the CacheSPI instance this cache loader is associated with.

Parameters:

manager - the region manager to use, or null.