org.jboss.cache.loader
Class AsyncCacheLoader

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

All Implemented Interfaces:

CacheLoader, org.jboss.system.Service

Direct Known Subclasses:

AsyncExtendedCacheLoader

public class AsyncCacheLoader
extends java.lang.Object
implements CacheLoader

The AsyncCacheLoader is a delegating cache loader that passes on all operations to an underlying CacheLoader. Read operations are done synchronously, while write (CRUD - Create, Remove, Update, Delete) operations are done asynchronously. There is no provision for exception handling at the moment for problems encountered with the underlying CacheLoader during a CRUD operation, and the exception is just logged. When configuring the CacheLoader, use the following attribute: <attribute name="CacheLoaderAsynchronous">true</attribute> to define whether cache loader operations are to be asynchronous. If not specified, a cache loader operation is assumed synchronous.

The following additional parameters are available:

cache.async.batchSize

Number of modifications to commit in one transaction, default is 100. The minimum batch size is 1.

cache.async.pollWait

How long to wait before processing an incomplete batch, in milliseconds. Default is 100. Set this to 0 to not wait before processing available records.

cache.async.returnOld

If true, this loader returns the old values from put(org.jboss.cache.Fqn, java.lang.Object, java.lang.Object) and remove(org.jboss.cache.Fqn, java.lang.Object) methods. Otherwise, these methods always return null. Default is true. false improves the performance of these operations.

cache.async.queueSize

Maximum number of entries to enqueue for asynchronous processing. Lowering this size may help prevent out-of-memory conditions. It also may help to prevent less records lost in the case of JVM failure. Default is 10,000 operations.

cache.async.put

If set to false, all put(org.jboss.cache.Fqn, java.lang.Object, java.lang.Object) operations will be processed synchronously, and then only the remove(org.jboss.cache.Fqn, java.lang.Object) operations will be processed asynchronously. This mode may be useful for processing expiration of messages within a separate thread and keeping other operations synchronous for reliability.

For increased performance for many smaller transactions, use higher values for cache.async.batchSize and cache.async.pollWait. For larger sized records, use a smaller value for cache.async.queueSize.

Author:

Manik Surtani (manik.surtani@jboss.com)

Field Summary

static int

DEFAULT_QUEUE_SIZE Default limit on entries to process asynchronously.

Constructor Summary

AsyncCacheLoader()

AsyncCacheLoader(CacheLoader cacheLoader)

Method Summary

void	commit(java.lang.Object tx) Commits the transaction.
void	create()
void	destroy()
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.
CacheLoader	getCacheLoader() Returns the delegate cache loader.
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 props) Sets the configuration.
void	start()
void	stop()
void	storeEntireState(byte[] state) Stores the entire state.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_QUEUE_SIZE

public static final int DEFAULT_QUEUE_SIZE

Default limit on entries to process asynchronously.

See Also:

Constant Field Values

Constructor Detail

AsyncCacheLoader

public AsyncCacheLoader()

AsyncCacheLoader

public AsyncCacheLoader(CacheLoader cacheLoader)

Method Detail

getCacheLoader

public CacheLoader getCacheLoader()

Returns the delegate cache loader.

setConfig

public void setConfig(java.util.Properties props)

Description copied from interface: CacheLoader

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

Specified by:

setConfig in interface CacheLoader

Parameters:

props - a collection of configuration properties

setCache

public void setCache(TreeCache c)

Description copied from interface: CacheLoader

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.

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

Description copied from interface: CacheLoader

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.

Specified by:

getChildrenNames in interface CacheLoader

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

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

Description copied from interface: CacheLoader

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.

Specified by:

get in interface CacheLoader

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

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

Description copied from interface: CacheLoader

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

Specified by:

exists in interface CacheLoader

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

Description copied from interface: CacheLoader

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.

Specified by:

put in interface CacheLoader

Throws:

java.lang.Exception

put

public void put(Fqn name,
                java.util.Map attributes)
         throws java.lang.Exception

Description copied from interface: CacheLoader

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

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

Description copied from interface: CacheLoader

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

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

Description copied from interface: CacheLoader

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.

Specified by:

remove in interface CacheLoader

Throws:

java.lang.Exception

remove

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

Description copied from interface: CacheLoader

Removes the given node and all its subnodes.

Specified by:

remove in interface CacheLoader

Throws:

java.lang.Exception

removeData

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

Description copied from interface: CacheLoader

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

Specified by:

removeData in interface CacheLoader

Throws:

java.lang.Exception

prepare

public void prepare(java.lang.Object tx,
                    java.util.List modifications,
                    boolean one_phase)
             throws java.lang.Exception

Description copied from interface: CacheLoader

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.

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

Throws:

java.lang.Exception

commit

public void commit(java.lang.Object tx)
            throws java.lang.Exception

Description copied from interface: CacheLoader

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

Specified by:

commit in interface CacheLoader

Parameters:

tx - transaction to commit

Throws:

java.lang.Exception

rollback

public void rollback(java.lang.Object tx)

Description copied from interface: CacheLoader

Rolls 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 - transaction to roll back

loadEntireState

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

Description copied from interface: CacheLoader

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 CacheLoader.storeEntireState(byte[]).

Specified by:

loadEntireState in interface CacheLoader

Throws:

java.lang.Exception

storeEntireState

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

Stores the entire state. This is processed asynchronously.

Specified by:

storeEntireState in interface CacheLoader

Throws:

java.lang.Exception

create

public void create()
            throws java.lang.Exception

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

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object