org.jumpi.impl.controller.ordering
Class SequentialController

java.lang.Object
  |
  +--org.jumpi.impl.AbstractController
        |
        +--org.jumpi.impl.controller.ordering.SequentialController

All Implemented Interfaces:

Component, Configurable, Controller, Manageable, Status, Status

public class SequentialController

extends AbstractController

implements Status

The SequentialController enforces single send and single receive operation concurrency over all the Connectors. A client application will block when submitting new send or receive operations when there is an operation already pending completion. The pending operation must complete or be cancelled before any new operations are processed.

Any number of Connectors are supported. A message is sent to or received from a single Connector, which is the first to support the Destination's Url, determined in configuration order. Supports any Destination Url syntax which the Connectors support.

The Destination Urls supported are those of the configured Connectors, without alteration.

Essentially compatible with all Connectors. Since sends and receives are strictly serialized over all Connectors, it may be more efficient to use the OrderingController to achieve serialization on a per Connector basis.

Field Summary

Fields inherited from class org.jumpi.impl.AbstractController

connectors_, joinFailInterval_, joinTestInterval_, jumpi_, name_, recvTransformer_, sendTransformer_, started_, stopping_

Fields inherited from interface org.jumpi.spi.Status

STATUS_RECEIVING, STATUS_SENDING

Fields inherited from interface org.jumpi.Status

STATUS_CANCELLED, STATUS_FAILURE, STATUS_SUCCESS, STATUS_TRANSIENT

Constructor Summary

SequentialController()

Method Summary

void	callbackRecv(Envelope env, boolean success, java.lang.String status) Notify of the recv operation completion by the Connector layer.
void	callbackSend(Envelope env, boolean success, java.lang.String status) Notify of the send operation completion by the Connector layer.
void	cancelRecv(Destination dest, Handle hdl) Cancels the recv operation, propagating this to the Connector layer if the operation has been passed to the Connector.
void	cancelSend(Destination dest, Handle hdl) Cancels the send operation, propagating this to the Connector layer if the operation has been passed to the Connector.
protected boolean	checkJoinCondition() Checks when the Controller has truly finished work after receiving a shutdown command.
Handle	recv(Destination dest, java.util.Hashtable clientProps) Receive a message from the Destination.
Handle	send(Destination dest, java.lang.Object msg, java.util.Hashtable clientProps) Send the message to the Destination.
protected void	shutdownState() Fail and remove any receive or send operations which are pending at the Connector layer.

Methods inherited from class org.jumpi.impl.AbstractController

configure, getDestination, getName, manage, transferInternalProperties

Methods inherited from class java.lang.Object

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

Constructor Detail

SequentialController

public SequentialController()

Method Detail

shutdownState

protected void shutdownState()

Fail and remove any receive or send operations which are pending at the Connector layer.

Specified by:

shutdownState in class AbstractController

checkJoinCondition

protected boolean checkJoinCondition()

Checks when the Controller has truly finished work after receiving a shutdown command. If there are no pending send or receive operations then, since no new operations can be started, we have a clean shutdown criteria.

Specified by:

checkJoinCondition in class AbstractController

Returns:

true when no receive or send operations are pending, else false.

send

public Handle send(Destination dest,
                   java.lang.Object msg,
                   java.util.Hashtable clientProps)

Send the message to the Destination. Send operations are serialized over all Connectors. If more than one send is issued by the client application, then the additional operations are blocked. It is not defined in which order blocked operations are unblocked. This is determined by the VM's thread notification. No message delivery guarantees are implemented over and above those provided by the Connector layer. Send operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to send and those passed down to the Connector layer.

The message format required on entry is not defined since messages are handled as opaque objects, subject to send transformation once before passing to the Connector.

Only one send operation can be handled at a time, irrespective of the Connector. Multiple sends are blocked until they can be handled.

Blocking or non blocking depending on the synchronization of the send method of the Connector. The caller's thread is used to delegate to the Connection layer. Therefore send may block if the Connector's send method blocks. If the Connector's send method is synchronous, then the method only returns once the send has completed at the Connector.

The message is passed to the Connector and resides in the STATUS_SENDING transient state until either cancelSend is called by the client application or callbackSend is called by the Connector.

Specified by:

send in interface Controller

Overrides:

send in class AbstractController

Parameters:

dest - the Destination to which the msg is to be sent.

msg - the message.

clientProps - not used but delegated in the Envelope to the Connector.

Returns:

a Handle associated to the send operation.

callbackSend

public void callbackSend(Envelope env,
                         boolean success,
                         java.lang.String status)

Notify of the send operation completion by the Connector layer. Since we only perform one send at a time, we expect to match up the last send Envelope with the returned value. This may not match up if a cancel took place, in which case a warning is logged. The next send operation which is blocked pending the completion at the Connector layer is triggered to continue.

Specified by:

callbackSend in interface Controller

Overrides:

callbackSend in class AbstractController

Parameters:

env - the Envelope used in Connector.send

success - true if successfully sent or false if a failure ocured.

status - a message giving more information to the status.

recv

public Handle recv(Destination dest,
                   java.util.Hashtable clientProps)

Receive a message from the Destination. Receive operations are serialized over all Connectors. If more than one receive is issued by the client applicaction, then the additional operations are blocked. It is not defined in which order blocked operations are unblocked. This is determined by the VM's thread notification. Receive operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to receive and those passed down to the Connector layer.

The message format required on entry is not defined since messages are handled as opaque objects, subject to receive transformation once before passing to the client application in the Handle.

Only one receive operation can be handled at a time, irrespective of the Connector. Multiple receives are blocked until they can be handled.

Blocking or non blocking depending on the synchronization of the receive method of the Connector. The caller's thread is used to delegate to the Connection layer. Therefore recv may block if the Connector's recv method blocks. If the Connector's recv method is synchronous, then the method only returns once the recv has completed at the Connector.

The message is passed to the Connector and resides in the STATUS_RECEIVING transient state until either cancelRecv is called by the client application or callbackRecv is called by the Connector.

Specified by:

recv in interface Controller

Overrides:

recv in class AbstractController

Parameters:

dest - the Destination from which a message is to be received.

clientProps - not used but delegated in the Envelope to the Connector.

Returns:

a Handle associated to the recv operation.

callbackRecv

public void callbackRecv(Envelope env,
                         boolean success,
                         java.lang.String status)

Notify of the recv operation completion by the Connector layer. Since we only perform one recv at a time, we expect to match up the last recv Envelope with the returned value. This may not match up if a cancel took place, in which case a warning is logged. The next recv operation which is blocked pending the completion at the Connector layer is triggered to continue.

Specified by:

callbackRecv in interface Controller

Overrides:

callbackRecv in class AbstractController

Parameters:

env - Envelope which has received a message or has failed at a Connector.

success - true if successful, else false.

status - description of the status.

cancelSend

public void cancelSend(Destination dest,
                       Handle hdl)

Cancels the send operation, propagating this to the Connector layer if the operation has been passed to the Connector. Trigger the next send operation to continue if we have removed the current send operation.

Specified by:

cancelSend in interface Controller

Overrides:

cancelSend in class AbstractController

Parameters:

dest - the Destination of the send operation associated to hdl.

hdl - the Handle associated with the send operation to cancel.

cancelRecv

public void cancelRecv(Destination dest,
                       Handle hdl)

Cancels the recv operation, propagating this to the Connector layer if the operation has been passed to the Connector. Trigger the next recv operation to continue if we have removed the current recv operation.

Specified by:

cancelRecv in interface Controller

Overrides:

cancelRecv in class AbstractController

Parameters:

dest - the Destination of the receive operation associated to hdl.

hdl - the Handle associated with the receive operation to cancel.