Jumpi v1.2.0

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:

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:

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.


Jumpi v1.2.0

Copyright 2003, Peter Jonathan Klauser.