net.sf.ehcache.constructs.asynchronous
Class AsynchronousCommandExecutor

java.lang.Object
  net.sf.ehcache.constructs.asynchronous.AsynchronousCommandExecutor

public final class AsynchronousCommandExecutor
extends java.lang.Object

Handles the asynchronous execution of commands. This class contains subtle threading interactions and should not be modified without comprehensive multi-threaded tests.

AsynchronousCommandExecutor is a singleton. Multiple clients may use it. It will execute commands in the order they were added per client. To preserve order, if a command cannot be executed, all commands will wait behind it.

This code requires JDK1.5 at present.

Version:

$Id: AsynchronousCommandExecutor.java 519 2007-07-27 07:11:45Z gregluck $

Author:

Greg Luck

Field Summary

static int	DEFAULT_DISPATCHER_THREAD_INTERVAL_SECONDS The dispatcher thread interval.
static java.lang.String	MESSAGE_CACHE The name of the message cache in the ehcache.xml configuration file.
static int	MINIMUM_SAFE_DISPATCHER_THREAD_INTERVAL Minimum setting for the dispatcher thread interval.
static java.lang.String	QUEUE_KEY The messageCache contains Command element values, and a queue that maintains their order.
static java.lang.String	SUCCESSFUL_EXECUTION The command completed successfully

Method Summary

int	countCachedPublishCommands()
void	dispose() ehcache also has a shutdown hook, so it will save all to disk.
(package private) java.lang.String	generateUniqueIdentifier() Generates an ID that is guaranteed to be unique for all VM invocations on a machine with a given IP address.
int	getExecuteAttemptsForCommand(java.lang.String uid) Gets the number of attempts for the command so far
static AsynchronousCommandExecutor	getInstance() Factory method to get an instance of MessageDispatcher.
Ehcache	getMessageCache() Gets the message cache
(package private) edu.emory.mathcs.backport.java.util.Queue	getQueue() Must be synchronized as potentially two threads could create new queues at the same time, with the result that one element would be lost.
java.lang.String	queueForExecution(Command command) Stores parameters in the MESSAGE_CACHE for later execution.
void	setDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds) Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.
void	setUnsafeDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds) Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.
(package private) java.lang.String	storeCommandToCache(net.sf.ehcache.constructs.asynchronous.AsynchronousCommandExecutor.InstrumentedCommand instrumentedCommand)

Methods inherited from class java.lang.Object

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

Field Detail

MESSAGE_CACHE

public static final java.lang.String MESSAGE_CACHE

The name of the message cache in the ehcache.xml configuration file.

See Also:

Constant Field Values

SUCCESSFUL_EXECUTION

public static final java.lang.String SUCCESSFUL_EXECUTION

The command completed successfully

See Also:

Constant Field Values

DEFAULT_DISPATCHER_THREAD_INTERVAL_SECONDS

public static final int DEFAULT_DISPATCHER_THREAD_INTERVAL_SECONDS

The dispatcher thread interval. It wakes up the dispatcher thread and attempts to process commands in the cache. Commands will ignore the execution request if they have a set time between retries. New messages dispatched, will also cause commands to be attempted immediately.

Setting this to a low value will cause high cpu load. The recommended value is the amount of time between failed message retries, which by default is 1 minute.

See Also:

Constant Field Values

MINIMUM_SAFE_DISPATCHER_THREAD_INTERVAL

public static final int MINIMUM_SAFE_DISPATCHER_THREAD_INTERVAL

Minimum setting for the dispatcher thread interval.

See Also:

DEFAULT_DISPATCHER_THREAD_INTERVAL_SECONDS, Constant Field Values

QUEUE_KEY

public static final java.lang.String QUEUE_KEY

The messageCache contains Command element values, and a queue that maintains their order. This is the key of the queue element.

See Also:

Constant Field Values

Method Detail

getInstance

public static AsynchronousCommandExecutor getInstance()
                                               throws AsynchronousCommandException

Factory method to get an instance of MessageDispatcher.

Returns:

a fully initialized reference to the singleton.

Throws:

AsynchronousCommandException

getQueue

edu.emory.mathcs.backport.java.util.Queue getQueue()
                                             throws AsynchronousCommandException

Must be synchronized as potentially two threads could create new queues at the same time, with the result that one element would be lost.

Returns:

the queue of messages, or if none existed, a new queue

Throws:

AsynchronousCommandException

getMessageCache

public Ehcache getMessageCache()
                        throws AsynchronousCommandException

Gets the message cache

Returns:

the MESSAGE_CACHE cache

Throws:

AsynchronousCommandException - if the MESSAGE_CACHE is null

queueForExecution

public java.lang.String queueForExecution(Command command)
                                   throws AsynchronousCommandException

Stores parameters in the MESSAGE_CACHE for later execution. A unique id is assigned to the PublisherCommand and that id is enqueued. Values stored will persist across VM restarts, provided the VM shutdown hooks have a chance to run.

This method is synchronized because the underlying Queue implementation is not threadsafe.

Parameters:

command - the Command which will be called on to publish the message

Returns:

the unique identifier for the command

Throws:

AsynchronousCommandException

getExecuteAttemptsForCommand

public int getExecuteAttemptsForCommand(java.lang.String uid)
                                 throws CommandNotFoundInCacheException,
                                        AsynchronousCommandException

Gets the number of attempts for the command so far

Parameters:

uid - - the unique id for the command returned from queueForExecution(Command)

Returns:

the number of times the command was executed

Throws:

CommandNotFoundInCacheException - if the command was not found in the cache.

AsynchronousCommandException - if their is a problem accessing the cache.

countCachedPublishCommands

public int countCachedPublishCommands()

Returns:

the approximate number of PublishCommands stored in the cache

dispose

public void dispose()

ehcache also has a shutdown hook, so it will save all to disk.

Shuts down the disk store in preparation for cache shutdown

If a VM crash happens, the shutdown hook will not run. The data file and the index file will be out of synchronisation. At initialisation we always delete the index file after we have read the elements, so that it has a zero length. On a dirty restart, it still will have and the data file will automatically be deleted, thus preserving safety.

storeCommandToCache

java.lang.String storeCommandToCache(net.sf.ehcache.constructs.asynchronous.AsynchronousCommandExecutor.InstrumentedCommand instrumentedCommand)
                               throws AsynchronousCommandException

Parameters:

instrumentedCommand -

Returns:

A unique id which acts as a handle to the message

Throws:

AsynchronousCommandException

generateUniqueIdentifier

java.lang.String generateUniqueIdentifier()

Generates an ID that is guaranteed to be unique for all VM invocations on a machine with a given IP address.

Returns:

A String representation of the unique identifier.

setDispatcherThreadIntervalSeconds

public void setDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds)
                                        throws java.lang.IllegalArgumentException

Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.

Parameters:

dispatcherThreadIntervalSeconds - the time in seconds

Throws:

java.lang.IllegalArgumentException - if the argument is less than 30

See Also:

for more information.

setUnsafeDispatcherThreadIntervalSeconds

public void setUnsafeDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds)

Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.

Provided with package local access to permit testing

Parameters:

dispatcherThreadIntervalSeconds - the time in seconds

See Also:

for more information.