org.jumpi.impl
Class AbstractConnector

java.lang.Object
  |
  +--org.jumpi.impl.AbstractConnector

All Implemented Interfaces:

Component, Configurable, Connector, Manageable, java.lang.Runnable, Task

Direct Known Subclasses:

DummyAsyncConnector, EmailConnector, JmsConnector, LoopbackConnector, MpiConnector, TcpConnector, UdpConnector

public abstract class AbstractConnector

extends java.lang.Object

implements Connector, Task

The AbstractConnector provides a simple abstract Connector implementation, where sends and receive operations are performed by a single thread, decoupled from the calling Controller thread. The Connector thread prioritizes send operations before receive operations. The Connector thread works off buffered send and receive operations by calling onSend and onRecv methods respectively. The onSend and onRecv methods are intended to be synchronous, and not return until the operation has either completed or has failed. Asynchronous send or receive operation can be achieved by subclasses implementing not only different onRecv or onSend methods, but also send and recv.

Field Summary

protected java.util.Vector	cancelledRecvs_ Buffered cancellations of recv operations waiting to be processed.
protected java.util.Vector	cancelledSends_ Buffered cancellations of send operations waiting to be processed.
protected Controller	controller_ Parent Controller instance.
protected int	joinFailInterval_ Time interval in milliseconds which must elapse before failing to shutdown cleanly.
protected int	joinTestInterval_ Time interval in milliseconds between checking the clean shutdown status.
protected Jumpi	jumpi_ The reverse link to the Jumpi instance at the root of the component tree.
protected int	maxRecvBacklog_ The maximum number of buffered recv operations before blocking receives.
protected int	maxSendBacklog_ The maximum number of buffered send operations before blocking sends.
protected java.lang.String	name_ The fully qualified component name.
protected java.lang.String	protocol_ The protocol part of Url's which are to be handled by the Connector.
protected BoundedQueue	recvQueue_ Buffered receive operations waiting to be processed.
protected Transformer	recvTransformer_ Transformer for messages being received from the network layer.
protected BoundedQueue	sendQueue_ Buffered send operations waiting to be processed.
protected Transformer	sendTransformer_ Transformer for messages being sent by the Controller.
protected boolean	started_ Whether the instance has been started.
protected boolean	stopping_ Whether the instance is shutting down.
protected java.lang.String	taskId_ The taskId of the instance's decoupled send and receive task.
protected java.lang.String	url_format_ The format of Url's which are supported.
protected java.lang.String	url_prefix_ The protocol suffixed with the protocol separator.

Constructor Summary

AbstractConnector()

Method Summary

void	cancelRecv(Envelope env) Cancel a receive operation.
void	cancelSend(Envelope env) Cancel a sending operation.
protected abstract boolean	checkJoinCondition() Check if a clean shutdown state has been reached after shutdown.
void	configure(java.lang.String name, Properties props) Configure the AbstractConnector.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Does not create any Destination.
java.lang.String	getName() Get the fully qualified name of the instance.
java.lang.String	getTaskId() A unique name for the task in the VM.
boolean	isLongRunning() The instance task is not running since it does not need its own thread and sends or receives individual messages.
boolean	isSchedulable() The instance is schedulable if there are any messages buffered in either the send or receive queues.
void	manage(Component root, Component parent, java.lang.String operation, java.util.Hashtable parameters) Perform a recursive management operation through the Jumpi component tree, using the parameters provided.
protected abstract boolean	onRecv(Envelope env) Synchronous recv called by the instance's task working off the buffered recv operations previously registered in recv().
protected abstract boolean	onSend(Envelope env) Synchronous send called by the instance's task working off the buffered send operations previously registered in send().
void	recv(Envelope env) Receive a message from the Destination given in the Envelope.
void	run() Process any buffered send operations and then buffered receive operations, taking into account operation cancellations, by delegating the operation to onSend and onRecv respectively.
void	send(Envelope env) Send a message to a Destination using information in the Envelope.
protected abstract void	shutdownState() Shutdown the instance.

Methods inherited from class java.lang.Object

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

Field Detail

jumpi_

protected Jumpi jumpi_

The reverse link to the Jumpi instance at the root of the component tree.

controller_

protected Controller controller_

Parent Controller instance.

protocol_

protected java.lang.String protocol_

The protocol part of Url's which are to be handled by the Connector.

name_

protected java.lang.String name_

The fully qualified component name.

sendTransformer_

protected Transformer sendTransformer_

Transformer for messages being sent by the Controller.

recvTransformer_

protected Transformer recvTransformer_

Transformer for messages being received from the network layer.

url_prefix_

protected java.lang.String url_prefix_

The protocol suffixed with the protocol separator.

url_format_

protected java.lang.String url_format_

The format of Url's which are supported.

sendQueue_

protected BoundedQueue sendQueue_

Buffered send operations waiting to be processed.

recvQueue_

protected BoundedQueue recvQueue_

Buffered receive operations waiting to be processed.

cancelledSends_

protected java.util.Vector cancelledSends_

Buffered cancellations of send operations waiting to be processed.

cancelledRecvs_

protected java.util.Vector cancelledRecvs_

Buffered cancellations of recv operations waiting to be processed.

maxSendBacklog_

protected int maxSendBacklog_

The maximum number of buffered send operations before blocking sends.

maxRecvBacklog_

protected int maxRecvBacklog_

The maximum number of buffered recv operations before blocking receives.

taskId_

protected java.lang.String taskId_

The taskId of the instance's decoupled send and receive task.

started_

protected boolean started_

Whether the instance has been started.

stopping_

protected boolean stopping_

Whether the instance is shutting down.

joinTestInterval_

protected int joinTestInterval_

Time interval in milliseconds between checking the clean shutdown status.

joinFailInterval_

protected int joinFailInterval_

Time interval in milliseconds which must elapse before failing to shutdown cleanly.

Constructor Detail

AbstractConnector

public AbstractConnector()

Method Detail

getDestination

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

Does not create any Destination. Subclass implementations should return a Destination instance associated with the given Destination Url. if the Url can be managed.

Specified by:

getDestination in interface Connector

Parameters:

url - the Destination Url.

clientProps - read-only properties are ignored..

Returns:

null always.

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. The default abstract implementation places the send operation onto a queue and returns immediately. The send is completed asynchronously by the instance's task. The send operation blocks if the send queue is full. The task asynchronously calls onSend to synchronously send the message.

Specified by:

send in interface Connector

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.

java.lang.IllegalStateException - when not started or stopping.

See Also:

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

onSend

protected abstract boolean onSend(Envelope env)
                           throws java.lang.Exception

Synchronous send called by the instance's task working off the buffered send operations previously registered in send(). Implementations must not call the Controller's callbackSend after send completion, this is performed on return from this call when returning with or without throwing an exception. Assuming the default run() method is used. The call should only return once the operation has completed or failed.

Parameters:

env - the Envelope registered in send().

Returns:

true if successful, otherwise false on a managed failure.

Throws:

java.lang.Exception - if any failure condition occurs, resulting in a failed send.

onRecv

protected abstract boolean onRecv(Envelope env)
                           throws java.lang.Exception

Synchronous recv called by the instance's task working off the buffered recv operations previously registered in recv(). Implementations must not call the Controller's callbackRecv after send completion, this is performed on return from this call when returning with or without throwing an exception. Assuming the default run() method is used. The method should only return once the operation has succeeded or failed.

Parameters:

env - the Envelope registered in recv().

Returns:

true on success, else false on a managed failure.

Throws:

java.lang.Exception - if any failure condition occurs.

recv

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

Receive a message from the Destination given in the Envelope. The default abstract implementation places the receive operation onto a queue and returns immediately. The receive is completed asynchronously by the instance's task. The receive operation blocks if the buffered recv queue is full. The task asynchronously calls onRecv to synchronously receive a message.

Specified by:

recv in interface Connector

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.

java.lang.IllegalStateException - when not started or stopping.

See Also:

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

cancelRecv

public void cancelRecv(Envelope env)

Cancel a receive operation. Buffered receive operations that are waiting in the queue to be processed by the instance's task may be removed before the task comes to working them off. This would be a cancel before actually starting the operation. Cancel does not remove from the task's buffered receive queue to avoid synchronization issues with the task instance's thread. The cancel intention is registered in the cancel receive queue and the task will manage canceling the operation when it has finished the current operation.

Specified by:

cancelRecv in interface Connector

Parameters:

env - the recv 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. Buffered send operations that are waiting in the queue to be sent by the instance's task may be removed before the task comes to working them off. This would be a cancel before actually starting the operation. Cancel does not remove the operation from the buffered send queue to avoid synchronization issues with the task instance's thread. The cancel intention is registered in the cancel send queue and the task will manage canceling the operation when it has finished the current operation.

Specified by:

cancelSend in interface Connector

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)

configure

public void configure(java.lang.String name,
                      Properties props)
               throws java.lang.Exception

Configure the AbstractConnector.

The following configuration attributes are defined:

• protocol - mandatory string

  The protocol which this connector supports.

• sendtransformer - optional string

  The classname of a transformer to transform data once per send. If not set, data is not transformed on send.

• recvtransformer - optional string

  The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.

• jointestinterval - optional integer [1000..MAX-INT] default 1000

  The time in milliseconds to check if the controller has finished during shutdown.

• joinfailinterval - integer[$jointestinterval..MAX-INT] - optional[30000].

  The time in milliseconds to before shutdown must complete, regardless if the controller are still running.

• maxsendbacklog - integer[1..MAX-INT] - optional[10].

  The maximum number of buffered send operations before blocking the caller for new send operations.

• maxrecvbacklog - integer[1..MAX-INT] - optional[10].

  The maximum number of buffered recv operations before blocking the caller for new recv operations.

Specified by:

configure in interface Configurable

Parameters:

name - the fully qualified instance name.

props - the read-only properties to configure the instance with.

Throws:

java.lang.Exception - when configuration is unsuccessful.

java.lang.IllegalArgumentException - if name or props are missing.

getName

public java.lang.String getName()

Get the fully qualified name of the instance. Identical to the name used in configure.

Specified by:

getName in interface Configurable

Returns:

the fully qualified name of the instance.

See Also:

configure(java.lang.String, org.jumpi.spi.Properties)

getTaskId

public java.lang.String getTaskId()

A unique name for the task in the VM.

Specified by:

getTaskId in interface Task

Returns:

a unique name for the task in the VM.

isSchedulable

public boolean isSchedulable()

The instance is schedulable if there are any messages buffered in either the send or receive queues.

Specified by:

isSchedulable in interface Task

Returns:

true if the send or receive queue have entries.

isLongRunning

public boolean isLongRunning()

The instance task is not running since it does not need its own thread and sends or receives individual messages.

Specified by:

isLongRunning in interface Task

Returns:

false always.

run

public void run()

Process any buffered send operations and then buffered receive operations, taking into account operation cancellations, by delegating the operation to onSend and onRecv respectively. The Controller is informed on the success or failure status of the send or receive respectively before processing the next buffered operation.

Specified by:

run in interface java.lang.Runnable

manage

public void manage(Component root,
                   Component parent,
                   java.lang.String operation,
                   java.util.Hashtable parameters)
            throws java.lang.Exception

Perform a recursive management operation through the Jumpi component tree, using the parameters provided. All operations are delegated to the send and receive transformers if configured.

The following management actions are handled:

• LINK. Link the instance with a Jumpi instance and the Controller parent. Assign a TaskId using a unique id from the Jumpi instance's SequenceGenerator.
• STARTUP. Note that instance is started. Send and Recv operations can be performed.
• SHUTDOWN. Note that instance is shutting down. Send and Recv operations can no longer be started. Calls shutdownState() which must remove all pending send and receive operations, not necessarily informing the Controller. The Controller shall handle the shutdown operation itself to manage the associated Handles status.
• JOIN. Wait for the send and receive operations to complete. A subclass should implement a waiting condition checkJoinCondition(), which informs the JOIN operation when it is safe to say the operations are complete. The shutdownState() is called again on JOIN since there is often race conditions in the SHUTDOWN operation since management operations are not necessarily tightly synchronized with normal send and receive operations. Any operations which successfully raced with the shutdown are to be disposed of again during the shutdownState called in the JOIN operation.
• UNLINK. Remove the link to the Jumpi instance and Controller parent.
• INFO. Adds an empty result to the Parameters.INFO_RESULT_SET using the component's fully qualified name as key.
• MANAGE. No operations defined.

Specified by:

manage in interface Manageable

Parameters:

root - the Jumpi instance at the root of the component tree.

parent - the immediate parent of the component.

operation - the operation.

parameters - the operation parameters.

Throws:

java.lang.Exception - if any failure to perform management occurs.

java.lang.IllegalArgumentException - when parameters are missing.

checkJoinCondition

protected abstract boolean checkJoinCondition()

Check if a clean shutdown state has been reached after shutdown.

Returns:

true if a clean shutdown state has been reached, else false.

shutdownState

protected abstract void shutdownState()

Shutdown the instance. Called twice during shutdown to avoid race condition of ongoing operations with the shutdown. First call on management shutdown, second call on management join.