org.jumpi.spi.component
Interface Connector

All Superinterfaces:

Component, Configurable, Manageable

All Known Implementing Classes:

AbstractConnector

public interface Connector

extends Component

A Connector is a low level communications protocol adapter which provides communications services to Controllers.

A Controller uses getDestination(java.lang.String, java.util.Hashtable) to determine if a the Connector can handle communications with the Destination Url. A Controller can only be asked to send or recv from a Destination which it has instantiated and returned via getDestination.

A Controller sends messages via the Connector with the send(org.jumpi.spi.Envelope) method. Whether the send method is blocking or not is Connector implementation dependent. The blocking behavior of a Connector on send must be well defined since Controllers need to take this aspect of dynamic behavior into account. Regardless of whether sends are blocking or not, the Controller.callbackSend(org.jumpi.spi.Envelope, boolean, java.lang.String) must be called by the Connector on send completion. The callbackSend may be called before the send method has returned. The callbackSend may be called with the same thread as is performing the send or a different thread. This is implementation dependent.

Whether multiple sends to different Destinations, or multiple sends to the different and the same destination, or only a single send at a time can be handled by a Connector is implementation dependent. This aspect of Connector behavior must be explicitly documented since a Controller may require certain concurrent send guarantees.

A Controller receives message via a Connector with the recv(org.jumpi.spi.Envelope) method. Whether the recv method is blocking or non is Connector implemetation dependent. The blocking behavior of a Connector on recv must be well defined since Controllers need to take this aspect of dynamic behavior into account. Regardless of whether receives are blocking or not, the Controller.callbackRecv(org.jumpi.spi.Envelope, boolean, java.lang.String) must be called by the Connector on receive completion, that is the matching of a receive with a received message. The callbackRecv may be called before the recv method has returned. The callbackRecv may be called with the same thread as is performing the recv or a different thread. This is implementation dependent.

Whether multiple receives from different Destinations, or multiple receives from the different and the same destination, or only a single receive at a time can be handled by a Connector is implementation dependent. This aspect of Connector behavior must be explicitly documented since a Controller may require certain concurrent receiving guarantees.

A Connector does not have to provide any message delivery guarantees like ordering or reliability. It is intended that the Controller ultimately determines which guarantees are provided to the Jumpi client application. All quality of service guarantees are implementation dependent.

Method Summary

void	cancelRecv(Envelope env) Cancel a receiving operation.
void	cancelSend(Envelope env) Cancel a sending operation.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Get a Destination instance associated with the given Destination Url, taking into account any read-only customization properties.
void	recv(Envelope env) Receive a message from the Destination given in the Envelope, placing it in the Envelope's context stack, and finally calling the Controller's callbackRecv.
void	send(Envelope env) Send a message to a Destination using information in the Envelope, finally calling the Controller's callbackSend on completion.

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 a Destination instance associated with the given Destination Url, taking into account any read-only customization properties. If the Destination Url cannot be handled by the Connector instance, then null is returned. The returned Destination should be associated with the Connector via Destination.getConnector(). If the Controller is known, then the Destination should be associated with the Controller via Destination.getController().

Parameters:

url - the Destination Url.

clientProps - read-only properties for implementation specific use.

Returns:

a Destination instance if the Connector can handle the Destination Url otherwise null.

Throws:

java.lang.IllegalArgumentException - when url is null.

send

public void send(Envelope env)
          throws java.lang.Exception

Send a message to a Destination using information in the Envelope, finally calling the Controller's callbackSend on completion. The Envelope contains all the information needed for the Connector to perform the sending. The Destination to which the message is to be sent is found with Envelope.getDestination(). Further information can be passed to the Connector from the Controller via the Envelope.getProperties() or from the client application with Envelope.getClientProperties(). The message data is in the Envelope's context stack, gettable via Envelope.popContext().

The send may be blocking or non blocking. The blocking behavior is implementation dependent. A non blocking send method may block in flow control situations.

The Connector is obliged to call the Controller's callbackSend method for each Envelope which is sent ( send method returns without Exception ), both successfully or unsuccessfully, unless cancelled. This calling may take place before send method has completed, in the case of blocking sends, or may take place at an unspecified time afterwards, in the case of non blocking sends. The thread to call the callbackSend may be the same thread as that used in the send or it may be a different thread.

The Controller is obliged to place the message to be sent on the Envelope's context stack. The message data can be used as the basis for transforming the message to a protocol specific format for transmission. The context stack prerequisites expected by the Connector are implementation dependent. The Envelope's context stack need not be preserved by the Connector. A Controller may place more than one message on the Envelope's context stack if a Connector can manage multiple sends with the same Envelope.

Send concurrency is implementation dependent. A Connector may not support concurrent sends, or may not support concurrent sends to the same Destination, or some other constraint.

A send operation ending successfully and callbackSend being called does not mean that the message has been received successfully. End to end delivery guarantees can only be given at the Controller layer.

Parameters:

env - the Envelope containing the message to be sent and the Destination.

Throws:

java.lang.Exception - if any failure condition occurs during the send method.

java.lang.IllegalArgumentException - when env is null.

See Also:

Controller.callbackSend(org.jumpi.spi.Envelope, boolean, java.lang.String)

recv

public void recv(Envelope env)
          throws java.lang.Exception

Receive a message from the Destination given in the Envelope, placing it in the Envelope's context stack, and finally calling the Controller's callbackRecv. The Envelope contains all the information needed for the Connector to perform the receive operation. The read-only customization properties from the Controller and Jumpi client application can be used to provide the Connector with additional information for the receiving operation.

The receive may be blocking or non blocking. The blocking behavior is implementation dependent. A non blocking receive method may block in flow control situations.

The Connector is obliged to call the Controller's callbackRecv method for each receive operation ( recv method returns without Exception ), both successfully or unsuccessfully, unless cancelled. This calling may take place before recv method has completed, in the case of blocking sends, or may take place at an unspecified time afterwards, in the case of non blocking sends. The thread to call the callbackRecv may be the same thread as that used in the send or it may be a different thread.

The Connector is obliged to place the received message on the Envelope's context stack via Envelope.pushContext(java.lang.Object). The message data may or may not have been transformed from a protocol or adapter specific format. The context stack prerequisites expected by the Controller for received messages are implementation dependent. A Connector may place more than one message on the Envelope's context stack if a Controller can manage multiple receives with the same Envelope.

The Connector is obliged to place the Destination representing the sender of the message in the Envelope so that the Controller can determine it via Envelope.getSender().

Receive concurrency is implementation dependent. A Connector may not support concurrent receives, or may not support concurrent receives from the same Destination, or some other constraint.

Whether wildcard receive operations are supported by the Connector is implementation dependent.

Parameters:

env - the Envelope which gives the Destination to receive from and where the received message is eventually placed with the sender.

Throws:

java.lang.Exception - if any failure condition occurs during the recv method.

java.lang.IllegalArgumentException - when env is null.

See Also:

Controller.callbackRecv(org.jumpi.spi.Envelope, boolean, java.lang.String)

cancelRecv

public void cancelRecv(Envelope env)

Cancel a receiving operation. If the Envelope is not known by the Connector or cancellation is not possible, then the operation is simply ignored. A Cancel operation may never block the calling thread.

Receive operations which have not completed may be cancellable. This behavior is implementation dependent. If an operation is successfully cancelled, then the callbackRecv of the Controller need not be called.

If an ongoing asynchronous receive operation cannot be cancelled ( currently stuck in an operating system method for example ) and the Connector can only handle one receive at a time ( or one receive per Destination at a time), then a Connector may perform the next receive operation before the uncancelled operation is complete since the cancel method never blocks. If confronted with this situation, a Connector may either fail the next receive operation or block the next receive operation as a flow control situation. The new receive operation should only complete once the ongoing cancelled operation has completed. This constraint requires that an ongoing operation will eventually complete in order to prevent deadlock.

Parameters:

env - the receive operation's Envelope to cancel.

Throws:

java.lang.IllegalArgumentException - when env is null.

See Also:

Controller.cancelRecv(org.jumpi.spi.Destination, org.jumpi.spi.Handle)

cancelSend

public void cancelSend(Envelope env)

Cancel a sending operation. If the Envelope is not known by the Connector or cancellation is not possible, then the operation is simply ignored. A Cancel operation may never block the calling thread.

Send operations which have not started or have not completed may be cancellable. This behavior is implementation dependent. If an operation is successfully cancelled, then the callbackSend of the Controller need not be called.

If an ongoing asynchronous send operation cannot be cancelled ( currently stuck in an operating system method for example ) and the Connector can only handle one send at a time ( or one send per Destination at a time), then a Connector may perform the next send operation before the uncancelled operation is complete, since the cancel method never blocks. If confronted with this situation, a Connector may either fail the next send operation or block the next send operation as a flow control situation. The new send operation should only complete once the ongoing cancelled operation has completed. This constraint requires that an ongoing operation will eventually complete in order to prevent deadlock.

Parameters:

env - the send operation's Envelope to cancel.

Throws:

java.lang.IllegalArgumentException - when env is null.

See Also:

Controller.cancelSend(org.jumpi.spi.Destination, org.jumpi.spi.Handle)