net.sf.ehcache.constructs.asynchronous

Class AsynchronousCommandExecutor

public final class AsynchronousCommandExecutor extends 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 191 2006-09-03 22:41:48Z gregluck $

Author: Greg Luck

Field Summary
static intDEFAULT_DISPATCHER_THREAD_INTERVAL_SECONDS
The dispatcher thread interval.
static StringMESSAGE_CACHE
The name of the message cache in the ehcache.xml configuration file.
static intMINIMUM_SAFE_DISPATCHER_THREAD_INTERVAL
Minimum setting for the dispatcher thread interval.
static StringQUEUE_KEY
The messageCache contains Command element values, and a queue that maintains their order.
static StringSUCCESSFUL_EXECUTION
The command completed successfully
Method Summary
intcountCachedPublishCommands()
voiddispose()
ehcache also has a shutdown hook, so it will save all to disk.
StringgenerateUniqueIdentifier()
Generates an ID that is guaranteed to be unique for all VM invocations on a machine with a given IP address.
intgetExecuteAttemptsForCommand(String uid)
Gets the number of attempts for the command so far
static AsynchronousCommandExecutorgetInstance()
Factory method to get an instance of MessageDispatcher.
EhcachegetMessageCache()
Gets the message cache
LinkedListgetQueue()
Must be synchronized as potentially two threads could create new queues at the same time, with the result that one element would be lost.
StringqueueForExecution(Command command)
Stores parameters in the MESSAGE_CACHE for later execution.
voidsetDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds)
Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.
voidsetUnsafeDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds)
Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.
StringstoreCommandToCache(AsynchronousCommandExecutor.InstrumentedCommand instrumentedCommand)

Field Detail

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.

MESSAGE_CACHE

public static final String MESSAGE_CACHE
The name of the message cache in the ehcache.xml configuration file.

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

QUEUE_KEY

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

SUCCESSFUL_EXECUTION

public static final String SUCCESSFUL_EXECUTION
The command completed successfully

Method Detail

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.

generateUniqueIdentifier

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.

getExecuteAttemptsForCommand

public int getExecuteAttemptsForCommand(String uid)
Gets the number of attempts for the command so far

Parameters: uid - the unique id for the command returned from queueForExecution

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.

getInstance

public static AsynchronousCommandExecutor getInstance()
Factory method to get an instance of MessageDispatcher.

Returns: a fully initialized reference to the singleton.

Throws: AsynchronousCommandException

getMessageCache

public Ehcache getMessageCache()
Gets the message cache

Returns: the MESSAGE_CACHE cache

Throws: AsynchronousCommandException if the MESSAGE_CACHE is null

getQueue

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

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

Throws: AsynchronousCommandException

queueForExecution

public String queueForExecution(Command command)
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

setDispatcherThreadIntervalSeconds

public void setDispatcherThreadIntervalSeconds(long dispatcherThreadIntervalSeconds)
Sets the interval between runs of the dispatch thread, when no new dispatch invocations have occurred.

Parameters: dispatcherThreadIntervalSeconds the time in seconds

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

storeCommandToCache

String storeCommandToCache(AsynchronousCommandExecutor.InstrumentedCommand instrumentedCommand)

Parameters: instrumentedCommand

Returns: A unique id which acts as a handle to the message

Throws: AsynchronousCommandException