org.lsst.ccs.messaging

Class ConcurrentMessagingUtils

java.lang.Object

org.lsst.ccs.messaging.ConcurrentMessagingUtils

public final class ConcurrentMessagingUtils
extends Object

Utility class to synchronously or asynchronously invoke or listen for events on the buses. Synchronous command execution will wait a given time before throwing a TimeoutException. The timeout used when throwing an exception depends on the method invoked, the ConcurrentMessagingUtils configuration and the command invoked. If a method that takes a timeout is invoked, that timeout is used, otherwise a cascade approach is used to determine the timeout among the following:

• The default timeout set on the ConcurrentMessagingUtils object, either at construction time or by invoking the method setDefaultTimeout method.
• The timeout value that comes from the annotated Command that is invoked
• The timeout returned as part of the CommandAck when the invoked Command is accepted

Of the above possible timeouts, the last one defined out of the presented order is picked and used. If none of the above timeouts is defined, an Exception will be thrown.

Author:

The LSST CCS Team

Constructor Summary

Constructors

Constructor and Description
ConcurrentMessagingUtils(AgentMessagingLayer agentMessagingLayer) ConsurrentMessagingUtils constructor.
ConcurrentMessagingUtils(AgentMessagingLayer agentMessagingLayer, Duration defaultTimeout) Build a ConsurrentMessagingUtils object with a default timeout.

Method Summary

Modifier and Type	Method and Description
Object	getAckForCommand(CommandRequest command, Duration timeout) Send a CommandRequest on the buses and synchronously wait for the Ack to come back within the provided Duration timeout.
Duration	getDefaultTimeout() Get the default timeout for this ConcurrentMessagingUtils object.
Future<Object>	sendAsynchronousCommand(CommandRequest command) Send a command on the buses and immediately return a Future that will asynchronously listen for the command reply.
Object	sendSynchronousCommand(CommandRequest command) Send synchronously a command on the Buses without a timeout.
Object	sendSynchronousCommand(CommandRequest command, Duration timeout) Send a command on the Buses and wait for the reply within the provided Duration timeout.
void	setDefaultTimeout(Duration defaultTimeout) Set the default timeout for this ConcurrentMessagingUtils object.
Future<StatusMessage>	startListeningForStatusBusMessage(Predicate<BusMessage<? extends Serializable,?>> f) Get a Future on a StatusBusMessage.
Future<StatusMessage>	startListeningForStatusBusMessage(Predicate<BusMessage<? extends Serializable,?>> filter, Duration timeout) Get a Future on a StatusBusMessage.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConcurrentMessagingUtils

public ConcurrentMessagingUtils(AgentMessagingLayer agentMessagingLayer)

ConsurrentMessagingUtils constructor.

Parameters:

agentMessagingLayer - The AgentMessagingLayer used to send messages on the buses.

ConcurrentMessagingUtils

public ConcurrentMessagingUtils(AgentMessagingLayer agentMessagingLayer,
                                Duration defaultTimeout)

Build a ConsurrentMessagingUtils object with a default timeout.

Parameters:

agentMessagingLayer - The AgentMessagingLayer used to send messages on the buses.

defaultTimeout - The default timeout used when synchronous commands are invoked.

Method Detail

setDefaultTimeout

public void setDefaultTimeout(Duration defaultTimeout)

Set the default timeout for this ConcurrentMessagingUtils object. The default timeout will be used to determine the timeout to be used when a synchronous method without a timeout is invoked.

Parameters:

defaultTimeout - The default timeout.

getDefaultTimeout

public Duration getDefaultTimeout()

Get the default timeout for this ConcurrentMessagingUtils object.

Returns:

The default timeout Duration.

sendSynchronousCommand

public Object sendSynchronousCommand(CommandRequest command)
                              throws Exception

Send synchronously a command on the Buses without a timeout. The timeout used will be the last one defined out of the following:

• default timeout
• timeout defined in the Command annotation
• timeout returned as part of the CommandAck

If none of the above is defined, an exception will be thrown.

Parameters:

command - The CommandRequest object to be sent on the buses.

Returns:

The reply of the CommandRequest.

Throws:

Exception - If an exception was fired by the remote execution of the command or the timeout expired or no valid timeout could be found.

sendSynchronousCommand

public Object sendSynchronousCommand(CommandRequest command,
                                     Duration timeout)
                              throws Exception

Send a command on the Buses and wait for the reply within the provided Duration timeout. If the command does not yield a reply within the provided timeout a TimeoutException will be thrown.

Parameters:

command - The CommandRequest object to be sent on the buses.

timeout - The Duration timeout. If the reply is not received within the timeout a TimeoutException will be thrown.

Returns:

The reply of the CommandRequest.

Throws:

Exception - If an exception was fired by the remote execution of the command or the timeout expired.

sendAsynchronousCommand

public Future<Object> sendAsynchronousCommand(CommandRequest command)

Send a command on the buses and immediately return a Future that will asynchronously listen for the command reply.

Parameters:

command - The CommandRequest object to be sent on the buses.

Returns:

A Future on the reply of the command execution. The future will also contain any possible exception thrown during the command execution.

getAckForCommand

public Object getAckForCommand(CommandRequest command,
                               Duration timeout)
                        throws Exception

Send a CommandRequest on the buses and synchronously wait for the Ack to come back within the provided Duration timeout.

Parameters:

command - The CommandRequest object to be sent on the buses.

timeout - Duration timeout. If the CommandAck is not received within the timeout a TimeoutException will be thrown.

Returns:

The CommandAck for the CommandRequest.

Throws:

Exception - If an exception was fired by the remote execution of the command or the timeout expired.

startListeningForStatusBusMessage

public Future<StatusMessage> startListeningForStatusBusMessage(Predicate<BusMessage<? extends Serializable,?>> filter,
                                                               Duration timeout)

Get a Future on a StatusBusMessage. The content of the Future is filled when the first StatusBusMessage that satisfies the ScriptingStatusBusMessageFilter is received. When the Future is exercised it will return the first ScriptingStatusBusMessage or an ExecutionException will be thrown when the timeout is reached.

Parameters:

filter - ScriptingStatusBusMessageFilter The message filter

timeout - Duration timeout, after which a ScriptiongTimeoutException is thrown. This timeout is from the time the method is invoked. If this timeout is reached an exception will be thrown if/when the Future is exercised.

Returns:

A Future on a ScriptingStatusBusMessage.

startListeningForStatusBusMessage

public Future<StatusMessage> startListeningForStatusBusMessage(Predicate<BusMessage<? extends Serializable,?>> f)

Get a Future on a StatusBusMessage. The content of the Future is filled when the first StatusBusMessage that satisfies the ScriptingStatusBusMessageFilter is received. When the Future is exercised it will return the first ScriptingStatusBusMessage.

Parameters:

f - ScriptingStatusBusMessageFilter The message filter

Returns:

A Future on a ScriptingStatusBusMessage.