org.jumpi.impl
Class AbstractController

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

All Implemented Interfaces:

Component, Configurable, Controller, Manageable

Direct Known Subclasses:

OrderingController, SequentialController, StatelessController

public abstract class AbstractController

extends java.lang.Object

implements Controller

The AbstractController provides basic utility functions for its subclasses, for example standard configuration and management options.

Field Summary

protected Connector[]	connectors_ The list of known configured Connectors.
protected int	joinFailInterval_ Time interval in milliseconds to abort waiting for a clean shutdown.
protected int	joinTestInterval_ Time interval in milliseconds to check whether the shutdown has completed cleanly.
protected Jumpi	jumpi_ The reverse link to the Jumpi instance at the root of the component tree.
protected java.lang.String	name_ The fully qualified component name.
protected Transformer	recvTransformer_ Transformer for messages being received from the Connection layer.
protected Transformer	sendTransformer_ Transformer for messages being sent by the client application.
protected boolean	started_ Whether the instance has been started.
protected boolean	stopping_ Whether shutdown has been called and the instance is stopping.

Constructor Summary

AbstractController()

Method Summary

void	callbackRecv(Envelope env, boolean success, java.lang.String status) Checks arguments and checks that the Controller is running.
void	callbackSend(Envelope env, boolean success, java.lang.String status) Checks arguments and checks that the Controller is running.
void	cancelRecv(Destination dest, Handle hdl) Checks arguments and checks that the Destination has a Controller which would allow cancellation of the receive towards the Controller.
void	cancelSend(Destination dest, Handle hdl) Checks arguments and checks that the Destination has a Controller which would allow cancellation of the send towards the Controller.
protected abstract boolean	checkJoinCondition() Checks when the Controller has truly finished work after receiving a shutdown command.
void	configure(java.lang.String name, Properties props) Configure the AbstractController.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Get the Destination associated with the Destination Url by matching the first Connector which agrees to manage the provided Url.
java.lang.String	getName() Get the fully qualified name of the instance.
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.
Handle	recv(Destination dest, java.util.Hashtable clientProps) Checks arguments and checks that the Controller has started, then returns a transient Handle which associates the clientProps and the Destination together.
Handle	send(Destination dest, java.lang.Object msg, java.util.Hashtable clientProps) Checks arguments and checks that the Controller has started, then returns a transient Handle which associates the message, clientProps and the Destination together.
protected abstract void	shutdownState() Shutdown the operation of the instance.
protected void	transferInternalProperties(Handle hdl, Envelope env) Copy any internal properties from EnvelopeImpl to Handle.

Methods inherited from class java.lang.Object

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

Field Detail

name_

protected java.lang.String name_

The fully qualified component name.

sendTransformer_

protected Transformer sendTransformer_

Transformer for messages being sent by the client application.

recvTransformer_

protected Transformer recvTransformer_

Transformer for messages being received from the Connection layer.

connectors_

protected Connector[] connectors_

The list of known configured Connectors.

jumpi_

protected Jumpi jumpi_

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

started_

protected boolean started_

Whether the instance has been started.

stopping_

protected boolean stopping_

Whether shutdown has been called and the instance is stopping.

joinTestInterval_

protected int joinTestInterval_

Time interval in milliseconds to check whether the shutdown has completed cleanly.

joinFailInterval_

protected int joinFailInterval_

Time interval in milliseconds to abort waiting for a clean shutdown.

Constructor Detail

AbstractController

public AbstractController()

Method Detail

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)

configure

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

Configure the AbstractController.

The following configuration attributes are defined:

• 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.

• connector - instancelist - mandatory.

  A list of comma separated component name suffixes of Connectors to instantiate and link to the Controller.

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.

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 and then any controllers.

The following management actions are handled:

• LINK. Link the instance with a Jumpi instance.
• STARTUP. Note that normal send and receive operations can take place.
• SHUTDOWN. Note that no new send and receive operations can take place. Calls shutdownState.
• JOIN. Calls shutdownState again and then waits until checkJoinCondition returns true or the join times-out.
• UNLINK. Remove the link to the Jumpi instance.
• 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()

Checks when the Controller has truly finished work after receiving a shutdown command. Return true when finished, otherwise false.

Sometimes threads or blocking operating system calls may require some time to complete after shutdown is called and the operations are asked to finish. The checkJoinCondition allows the join management call to wait for a clean shutdown.

Returns:

true when truly finished after shutdown, else false.

shutdownState

protected abstract void shutdownState()

Shutdown the operation of the instance. This is called on the management operations for SHUTDOWN and JOIN. Since the SHUTDOWN operation may be in a race condition with on going send and receive operations. The shutdownState method must manage being called twice. Any active send or receive operations may be terminated forcibly on SHUTDOWN.

getDestination

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

Get the Destination associated with the Destination Url by matching the first Connector which agrees to manage the provided Url. If send or receive operations to the the Destination Url cannot be managaged a the Controller, then null is returned.

Specified by:

getDestination in interface Controller

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)

Checks arguments and checks that the Controller has started, then returns a transient Handle which associates the message, clientProps and the Destination together. No delegation to the Controller layer is performed.

Specified by:

send in interface Controller

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 transient Handle associated to the send operation.

Throws:

java.lang.IllegalArgumentException - when dest is null.

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

See Also:

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

recv

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

Checks arguments and checks that the Controller has started, then returns a transient Handle which associates the clientProps and the Destination together. No delegation to the Controller layer is performed.

Specified by:

recv in interface Controller

Parameters:

dest - the Destination from which to receive a message.

clientProps - read-only properties for implementation specific use.

Returns:

a transient Handle associated to the receive operation.

Throws:

java.lang.IllegalArgumentException - when dest is null.

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

See Also:

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

cancelSend

public void cancelSend(Destination dest,
                       Handle hdl)

Checks arguments and checks that the Destination has a Controller which would allow cancellation of the send towards the Controller.

Specified by:

cancelSend in interface Controller

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.

java.lang.IllegalStateException - when the Handle's connector is null.

See Also:

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

cancelRecv

public void cancelRecv(Destination dest,
                       Handle hdl)

Checks arguments and checks that the Destination has a Controller which would allow cancellation of the receive towards the Controller.

Specified by:

cancelRecv in interface Controller

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.

java.lang.IllegalStateException - when the Handle's connector is null.

See Also:

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

callbackSend

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

Checks arguments and checks that the Controller is running. Otherwise does not do any relevant processing. This must be implemented in subclasses.

Specified by:

callbackSend in interface Controller

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.

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

See Also:

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

callbackRecv

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

Checks arguments and checks that the Controller is running. Otherwise does not do any relevant processing. This must be implemented in subclasses.

Specified by:

callbackRecv in interface Controller

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.

Throws:

java.lang.IllegalArgumentException - when env is null.

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

See Also:

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

transferInternalProperties

protected void transferInternalProperties(Handle hdl,
                                          Envelope env)

Copy any internal properties from EnvelopeImpl to Handle.

Parameters:

hdl - all the EnvelopeImpl's internal properties are copied to this Handle.

env - all this EnvelopeImpl's internal properties are copied to the Handle.