Jumpi v1.2.0

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:

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:

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.

Jumpi v1.2.0

Copyright 2003, Peter Jonathan Klauser.