org.jboss.cache.loader
Interface CacheLoader

All Superinterfaces:
org.jboss.system.Service
All Known Subinterfaces:
CacheLoaderAop, ExtendedCacheLoader
All Known Implementing Classes:
AsyncCacheLoader, AsyncExtendedCacheLoader, BdbjeCacheLoader, ChainingCacheLoader, ClusteredCacheLoader, DelegatingCacheLoader, FileCacheLoader, FileExtendedCacheLoader, JDBCCacheLoader, JDBCExtendedCacheLoader, JdbmCacheLoader, LocalDelegatingCacheLoader, RmiDelegatingCacheLoader, RpcDelegatingCacheLoader, SharedStoreCacheLoader, TcpDelegatingCacheLoader

public interface CacheLoader
extends org.jboss.system.Service

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(java.util.Properties) ) and cache (setCache(TreeCache)) are set. After this, Service.create() is called. Then Service.start() is called. When re-deployed, Service.stop() will be called, followed by another Service.start(). Finally, when shut down, Service.destroy() is called, after which the loader is unusable.

Version:
$Id: CacheLoader.java,v 1.5 2006/04/02 07:33:15 genman Exp $
Author:
Bela Ban Oct 31, 2003

Method Summary
 void commit(java.lang.Object tx)
          Commits the transaction.
 boolean exists(Fqn name)
          Returns true if the CacheLoader has a node with a Fqn.
 java.util.Map get(Fqn name)
          Returns all keys and values from the persistent store, given a fully qualified name.
 java.util.Set getChildrenNames(Fqn fqn)
          Returns a set of children node names as Strings.
 byte[] loadEntireState()
          Fetches the entire state for this cache from secondary storage (disk, DB) and returns it as a byte buffer.
 void prepare(java.lang.Object tx, java.util.List modifications, boolean one_phase)
          Prepares a list of modifications.
 void put(Fqn name, java.util.Map 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.
 java.lang.Object put(Fqn name, java.lang.Object key, java.lang.Object value)
          Puts a key and value into the attribute map of a given node.
 void put(java.util.List modifications)
          Applies all modifications to the backend store.
 void remove(Fqn name)
          Removes the given node and all its subnodes.
 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 or any subnodes.
 void rollback(java.lang.Object tx)
          Rolls the transaction back.
 void setCache(TreeCache c)
          Sets the TreeCache that is maintaining this CacheLoader.
 void setConfig(java.util.Properties properties)
          Sets the configuration.
 void storeEntireState(byte[] state)
          Stores the given state in secondary storage.
 
Methods inherited from interface org.jboss.system.Service
create, destroy, start, stop
 

Method Detail

setConfig

void setConfig(java.util.Properties properties)
Sets the configuration. This is called before Service.create() and Service.start().

Parameters:
properties - a collection of configuration properties

setCache

void setCache(TreeCache c)
Sets the TreeCache that is maintaining this CacheLoader. This method allows this CacheLoader to invoke methods on TreeCache, including fetching additional configuration information. This method is called be called after the CacheLoader instance has been constructed.

Parameters:
c - The cache on which this loader works

getChildrenNames

java.util.Set getChildrenNames(Fqn fqn)
                               throws java.lang.Exception
Returns a set of children node names as Strings. 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(Set) to make the set unmodifiable.

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:
java.lang.Exception

get

java.util.Map get(Fqn name)
                  throws java.lang.Exception
Returns all keys and values from the persistent store, given a fully qualified name. NOTE that the expected return value of this method has changed from JBossCache 1.2.x and before! This will affect cache loaders written prior to JBossCache 1.3.0 and such implementations should be checked for compliance with the behaviour expected.

Parameters:
name -
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:
java.lang.Exception

exists

boolean exists(Fqn name)
               throws java.lang.Exception
Returns true if the CacheLoader has a node with a Fqn.

Returns:
true if node exists, false otherwise
Throws:
java.lang.Exception

put

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

put

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

Parameters:
name - The fully qualified name of the node
attributes - A Map of attributes. Can be null
Throws:
java.lang.Exception

put

void put(java.util.List modifications)
         throws java.lang.Exception
Applies all modifications to the backend store. Changes may be applied in a single operation.

Parameters:
modifications - A List of modifications
Throws:
java.lang.Exception

remove

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. Does nothing if the node doesn't exist Returns the removed value.

Throws:
java.lang.Exception

remove

void remove(Fqn name)
            throws java.lang.Exception
Removes the given node and all its subnodes.

Throws:
java.lang.Exception

removeData

void removeData(Fqn name)
                throws java.lang.Exception
Removes all attributes from a given node, but doesn't delete the node itself or any subnodes.

Throws:
java.lang.Exception

prepare

void prepare(java.lang.Object tx,
             java.util.List modifications,
             boolean one_phase)
             throws java.lang.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 coresponding SQL statements against the DB (statements derived from modifications)
For non-transactional CacheLoader (e.g. file-based), this could be a null operation.

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

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

rollback

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

byte[] loadEntireState()
                       throws java.lang.Exception
Fetches the entire state for this cache from secondary storage (disk, DB) and returns it as a byte buffer. This is for initialization of a new cache from a remote cache. The new cache would then call storeEntireState(byte[]).

Throws:
java.lang.Exception

storeEntireState

void storeEntireState(byte[] state)
                      throws java.lang.Exception
Stores the given state in secondary storage. Overwrites whatever is currently in storage.

Throws:
java.lang.Exception


Copyright 1998-2005 JBoss Inc . All Rights Reserved.