org.jumpi.spi.component
Interface Controller

All Superinterfaces:

Component, Configurable, Manageable

All Known Implementing Classes:

AbstractController

public interface Controller

extends Component

A Controller manages all communications operations between a Jumpi instance and protocol specific Connectors, to provide communication guarantees. A Controller can provide communications guarantees like reliability and ordering above unreliable, non order preserving Connectors. Controllers are protocol independent since they and do not directly perform any low level communications themselves. All communications operations are performed via Connectors which are protocol specific communication adapters.

The following are examples of possible Controllers:

• A Controller which does nothing but delegate send and receive operations from a Jumpi instance to the protocol specific Connector. A Jumpi client application must make sure that Connector is used correctly, for example by ensuring that the message formats required by the Connector are used on send, or that no concurrent sending takes place if the Connector doesn't support it.
• A Controller which orders message send and receive operations such that only one send or receive operation per Destination is active at a Connector at one time. This would allow a Jumpi client application to send multiple sends to the same Destination at once, and the Controller handles this transparently.
• A Controller which provides reliable delivery of messages. A send operation is only marked as successfully completed to the Jumpi client application when a peer Controller instance has acknowledged the reception of the message. Such a Controller can determine a numbering scheme itself, or a numbering scheme can be defined by the Jumpi client application in the send data. The Controller can perform retransmissions if sends at the Connector layer fail.
• A Controller which provides redundant message delivery. A single send operation from a Jumpi client application is sent via multiple Controllers concurrently.
• A Controller like the reliable delivery Controller described above but which also stores messages in persistent store such that VM crashes do not result in message loss.
• A Controller which provides transactional guarantees. Not only are messages delivered reliably, but sent messages are only completed successfully when the Jumpi client application which received them acknowledges their receipt.

When a Jumpi client application requests a Destination from a Jumpi instance with Jumpi.getDestination(java.lang.String, java.lang.String, java.util.Hashtable), the Jumpi instance delegates the request to the associated Controller or to the default Controller. The Controller must return a Destination instance associated with the provided Destination Url if the Destination Url can be handled by the Controller. Once the link is associated with the Destination, send and receive operations can be requested for the Destination.

A Jumpi.send(org.jumpi.Destination, java.lang.Object, org.jumpi.Selector, java.util.Hashtable) operation is delegated by the Jumpi instance to the Controller responsible for the send's Destination. The Controller returns a Handle back to the Jumpi instance which is given to the Jumpi client application and handles the sending operation in its own implementation dependent way using any configured Connectors. The send operation may or may not block. This is implementation dependent. Blocking send operations only return the Handle to the caller when the send operation is completed, either successfully or failed. Non blocking send operations may or may not have completed before the Handle is returned to the caller.

A Jumpi.recv(org.jumpi.Destination, org.jumpi.Selector, java.util.Hashtable) operation is delegated by the Jumpi instance to the Controller responsible for the receive's Destination. The Controller returns a Handle back to the Jumpi instance which is given to the Jumpi client application and handles the receiving operation in its own implementation dependent way using any configured Connectors. The receive operation may or may not block. This is implementation dependent. Blocking receive operations only return the Handle to the caller when the receive operation is completed, either successfully or failed. Non blocking receive operations may or may not have completed before the Handle is returned to the caller.

Controllers may or may not be tightly linked to individual Connectors, since Connector behavior may be very different. For example blocking behaviour and concurrency of send or receive operations is implementation dependent. A Controller may only function correctly for non blocking Connectors. The Controller must make sure that an operation's Envelope has a correct message data contained in the context stack, for the Connector. The Controller may require certain message data formats from a Jumpi client application in order to be able to fullfill its contract with the Connectors. The compatibility between Controller and Connector must be explicity defined.

Method Summary

void	callbackRecv(Envelope env, boolean success, java.lang.String status) Callback called by Connector to signal completion of a Connector receive operation.
void	callbackSend(Envelope env, boolean success, java.lang.String status) Callback called by Connector to signal completion of a Connector send operation.
void	cancelRecv(Destination dest, Handle hdl) Cancel a receive operation.
void	cancelSend(Destination dest, Handle hdl) Cancel a send operation.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Get the Destination associated with the Destination Url.
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.

Methods inherited from interface org.jumpi.spi.Configurable

configure, getName

Methods inherited from interface org.jumpi.spi.Manageable

manage

Method Detail

getDestination

public Destination getDestination(java.lang.String url,
                                  java.util.Hashtable clientProps)

Get the Destination associated with the Destination Url. The read-only client properties may provide implementation dependent information. If send or receive operations to the the Destination Url cannot be managaged by the Controller, then null is returned.

Parameters:

url - the Destination Url.

clientProps - read-only properties for implementation specific use.

Returns:

the Destination instance if the Controller can handle operations to the Destination Url, otherwise null.

Throws:

java.lang.IllegalArgumentException - when url is null.

See Also:

Connector.getDestination(java.lang.String, java.util.Hashtable)

send

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

Send the message to the Destination. The read-only properties are for implementation specific use. Send operations are delegated to Connectors. There is not a 1:1 relationship between calls to send and those passed down to the Connector layer. This is implementation dependent.

The message format required on entry is implementation dependent. The Controller is responsible for satisfying the Connector.send(org.jumpi.spi.Envelope) requirements.

Message delivery guarantees are implementation dependent. The send method may block. This is implementation specific. So too is the concurrency behaviorof the Controller. A Controller may be able to handle multiple concurrent sends, but need not.

Parameters:

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

msg - the message.

clientProps - read-only properties for implementation specific use.

Returns:

a Handle associated to the send operation.

Throws:

java.lang.IllegalArgumentException - when dest is null.

See Also:

Connector.send(org.jumpi.spi.Envelope)

recv

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

Receive a message from the Destination. The read-only properties are for implementation specific use. Receive operations are delegated to Connectors. There is not a 1:1 relationship between calls to recv and those passed down to the Connector layer. This is implementation dependent.

The message format required on entry is implementation dependent. The Controller is responsible for reading the received message from the Connector specific data provided in the callbackRecv's Envelope, and providing the message ultimately in a well defined format for the Jumpi client application.

The recv method may block. This is implementation specific. So too is the concurrency behaviorof the Controller. A Controller may be able to handle multiple concurrent receives, but need not.

On completion of the receive operation, the Controller must make sure that the Jumpi client guarantee for the associated Handle is upheld. The received message must be availbile throught Handle.getMessage() and the sender is through Handle.getSender().

Parameters:

dest - the Destination from which to receive a message.

clientProps - read-only properties for implementation specific use.

Returns:

a Handle associated to the receive operation.

Throws:

java.lang.IllegalArgumentException - when dest is null.

See Also:

Connector.recv(org.jumpi.spi.Envelope)

cancelSend

public void cancelSend(Destination dest,
                       Handle hdl)

Cancel a send operation. Jumpi client applications use Handle.cancel() to cancel asynchronous send and receive operations. Each Handle is linked to the Controller which instantiated it and is linked to a Destination for the operation. The cancellation of a Handle is delegated to the responsible Connector, in the case of a send operation to cancelSend. The cancel method must never block.

The Controller can free resources and delegate the cancel to the Connector layer so that low level resources can be freed, for operations which are not needed anymore.

Parameters:

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

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

Throws:

java.lang.IllegalArgumentException - when dest or hdl is null.

See Also:

Connector.cancelSend(org.jumpi.spi.Envelope)

cancelRecv

public void cancelRecv(Destination dest,
                       Handle hdl)

Cancel a receive operation. Jumpi client applications use Handle.cancel() to cancel asynchronous send and receive operations. Each Handle is linked to the Controller which instantiated it and is linked to a Destination for the operation. The cancellation of a Handle is delegated to the responsible Connector, in the case of a receive operation to cancelRecv. The cancel method must never block.

The Controller can free resources and delegate the cancel to the Connector layer so that low level resources can be freed, for operations which are not needed anymore.

Parameters:

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

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

Throws:

java.lang.IllegalArgumentException - when dest or hdl is null.

See Also:

Connector.cancelRecv(org.jumpi.spi.Envelope)

callbackSend

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

Callback called by Connector to signal completion of a Connector send operation. The success status and status message are provided by the Connector. A Connector will always call callbackSend after completion unless a cancel has been performed for the Envelope at the Connector. Due to multithreading and synchronization, a Controller can expect callbackSend to be called whilst calling Connector.cancelSend.

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.

Throws:

java.lang.IllegalArgumentException - when env is null.

See Also:

Connector.send(org.jumpi.spi.Envelope)

callbackRecv

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

Callback called by Connector to signal completion of a Connector receive operation. The success status and status message are provided by the Connector. A Connector will always call callbackRecv after completion unless a cancel has been performed for the Envelope at the Connector. Due to multithreading and synchronization, a Controller can expect callbackRecv to be called whilst calling Connector.cancelRecv.

If successfully completed, the Envelope must contain the message data on the Envelope's context stack with Envelope.popContext(), and the sender must be available with Envelope.getSender()

Parameters:

env - the Envelope used in Connector.recv

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

status - a message giving more information to the status.

Throws:

java.lang.IllegalArgumentException - when env is null.

See Also:

Connector.recv(org.jumpi.spi.Envelope)