Jumpi v1.2.0

org.jumpi.impl
Class HandleImpl

java.lang.Object
  |
  +--org.jumpi.impl.HandleImpl
All Implemented Interfaces:
Handle, Handle, Status, Status

public class HandleImpl
extends java.lang.Object
implements Handle, Status

An Handle carries status information about pending or finished send and receive operations. It allows inquiry of the state information and received messages and the sender. Handles can be used to for synchronization, when a Jumpi client application wants to wait for pending operations to complete before continuing.


Field Summary
 
Fields inherited from interface org.jumpi.spi.Status
STATUS_RECEIVING, STATUS_SENDING
 
Fields inherited from interface org.jumpi.Status
STATUS_CANCELLED, STATUS_FAILURE, STATUS_SUCCESS, STATUS_TRANSIENT
 
Constructor Summary
HandleImpl(int status, java.lang.Object msg, Destination dest, Controller controller, boolean send)
          Creates a new HandleImpl object.
HandleImpl(int status, java.lang.String statusMessage, boolean send)
          Creates a new HandleImpl object.
HandleImpl(int status, java.lang.String statusMessage, java.lang.Object msg, Destination dest, Controller controller, boolean send)
          Creates a new HandleImpl object.
 
Method Summary
 void addSelector(Selector selector)
          Add the Selector to the list of Selectors to which the Handle belongs.
 void assertStatusCode(int status, java.lang.String errorMessage)
          Throw an Exception with the provided error message if the status code does not match the provided value.
 void cancel()
          Immediately cancel the send or receive operation associated with the Handle.
static Handle createFailedHandle(java.lang.String statusMsg, boolean send)
          Create a failed, non blocking Handle given a status message and whether the Handle is a send or receive Handle.
static Handle createTransientHandle(Destination dest, java.util.Hashtable clientProps, Controller controller, boolean send)
          Create a transient send or receive Handle belonging to a Controller, addressed to a Destination with optional client properties.
static Handle createTransientHandle(java.lang.Object msg, Destination dest, java.util.Hashtable clientProps, Controller controller, boolean send)
          Create a transient send or receive Handle belonging to a Controller, addressed to a Destination with optional message and client properties.
 void ensureProperties()
          Ensure that there is a Hashtable for implementation specific Properties which will be returned to a Jumpi client application with getProperties().
 java.util.Hashtable getClientProperties()
          Returns the read-only client properties as used in Jumpi.send() or Jumpi.recv() when blocking, otherwise null.
 Controller getController()
          Get the Controller instance responsible for the Handle.
 Destination getDestination()
          Gets the Destination to which a message is being sent or being received from.
 java.lang.Object getMessage()
          Return the message being sent or which has been received.
 java.util.Hashtable getProperties()
          Returns additional information concerning the send or receive operation to the Jumpi client application.
 Destination getSender()
          Get the Destination representation of the sender of a received message.
 int getStatus()
          Get the internal status code of the Handle.
 int getStatusCode()
          Returns the current Status of the Handle.
 java.lang.String getStatusMessage()
          Return the current status message.
 boolean isBlocking()
          Returns true when the Handle's status is blocking, that is, getStatusCode() returns STATUS_TRANSIENT, otherwise false.
 boolean isNonBlocking()
          Returns true when the Handle's status is non blocking, that is, getStatusCode() does NOT return STATUS_TRANSIENT, otherwise false.
 boolean isRecvHandle()
          Whether the Handle is associated with a receive operation or not.
 boolean isSendHandle()
          Whether the Handle is associated with a send operation or not.
 void removeProperties()
          Ensure that there are no implementation specific Properties which will be returned to a Jumpi client application with getProperties().
 void removeSelector(Selector selector)
          Remove the Selector from the list of Selectors to which the Handle belongs.
 void setClientProperties(java.util.Hashtable props)
          Sets the read-only client properties as used in Jumpi.send() or Jumpi.recv().
 void setController(Controller controller)
          Set the Controller instance responsible for the Handle.
 void setDestination(Destination dest)
          Sets the Destination to which a message is being sent or being received from.
 void setMessage(java.lang.Object msg)
          Set the message being sent or which has been received.
 void setSender(Destination sender)
          Set the Destination which represents the sender of a received message.
 void setStatus(int status)
          Set the status of the Handle and a status message.
 void setStatus(int status, java.lang.Object msg)
          Set the status of the Handle and a message received.
 void setStatus(int status, java.lang.String statusMessage)
          Set the status of the Handle and a status message.
 void setStatus(int status, java.lang.String statusMessage, java.lang.Object msg)
          Set the status of the Handle and a message and status message.
 void setStatusMessage(java.lang.String statusMessage)
          Set the current status message.
 void waitWhileBlocking()
          Wait for an unlimited time until the status of the Handle becomes non blocking.
 void waitWhileBlocking(long timeout)
          Wait for a limited time until the status of the Handle becomes non blocking.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HandleImpl

public HandleImpl(int status,
                  java.lang.Object msg,
                  Destination dest,
                  Controller controller,
                  boolean send)
Creates a new HandleImpl object.

Parameters:
status - the current state of the Handle.
msg - the message being sent or received.
dest - the Destination to which the message is sent or received from.
controller - the controller responsible for the operation.
send - whether the operation is a send or receive operation.

HandleImpl

public HandleImpl(int status,
                  java.lang.String statusMessage,
                  boolean send)
Creates a new HandleImpl object.

Parameters:
status - the current state of the Handle.
statusMessage - the current status message.
send - whether the operation is a send or receive operation.

HandleImpl

public HandleImpl(int status,
                  java.lang.String statusMessage,
                  java.lang.Object msg,
                  Destination dest,
                  Controller controller,
                  boolean send)
Creates a new HandleImpl object.

Parameters:
status - the current state of the Handle.
statusMessage - the current status message.
msg - the message to be sent or the message received.
dest - the Destination to send the message to or to receive from.
controller - the responsible Controller.
send - true if associated with a send operation, else false.
Method Detail

addSelector

public void addSelector(Selector selector)
Add the Selector to the list of Selectors to which the Handle belongs. Handles are linked to Selectors and Selectors linked to Handles. No uniqueness check on selectors is performed.

Specified by:
addSelector in interface Handle
Parameters:
selector - the Selector to which this instance belongs.
Throws:
java.lang.IllegalArgumentException - if selector is null.
See Also:
Selector.addHandle(org.jumpi.Handle)

removeSelector

public void removeSelector(Selector selector)
Remove the Selector from the list of Selectors to which the Handle belongs. Handles are linked to Selectors and Selectors linked to Handles. No uniqueness check on selectors is performed.

Specified by:
removeSelector in interface Handle
Parameters:
selector - the Selector to which this instance no longer belongs.
Throws:
java.lang.IllegalArgumentException - if selector is null.
See Also:
Selector.clear(), Selector.removeHandle(org.jumpi.Handle)

createFailedHandle

public static Handle createFailedHandle(java.lang.String statusMsg,
                                        boolean send)
Create a failed, non blocking Handle given a status message and whether the Handle is a send or receive Handle.

Parameters:
statusMsg - the failure status message.
send - true if the Handle is a sendHandle, otherwise false.
Returns:
a non blocking, failed Handle.

createTransientHandle

public static Handle createTransientHandle(java.lang.Object msg,
                                           Destination dest,
                                           java.util.Hashtable clientProps,
                                           Controller controller,
                                           boolean send)
Create a transient send or receive Handle belonging to a Controller, addressed to a Destination with optional message and client properties.

Parameters:
msg - the message to send or the received message.
dest - the Destination to send the message to or receive the message from.
clientProps - optional read-only client customization properties.
controller - the Controller responsible for the Handle.
send - true if the Handle is a sendHandle, otherwise false.
Returns:
the transient Handle with the attributes given in the parameters.

createTransientHandle

public static Handle createTransientHandle(Destination dest,
                                           java.util.Hashtable clientProps,
                                           Controller controller,
                                           boolean send)
Create a transient send or receive Handle belonging to a Controller, addressed to a Destination with optional client properties.

Parameters:
dest - the Destination to send the message to or receive the message from.
clientProps - optional read-only client customization properties.
controller - the Controller responsible for the Handle.
send - true if the Handle is a sendHandle, otherwise false.
Returns:
the transient Handle with the attributes given in the parameters.

getStatusCode

public int getStatusCode()
Returns the current Status of the Handle. All specific transient internal states are mapped onto STATUS_TRANSIENT.

Specified by:
getStatusCode in interface Handle
Returns:
the current Status of the Handle.
See Also:
Status

getStatus

public int getStatus()
Get the internal status code of the Handle. Unlike getStatusCode, the getStatus does not map the internal status code at all.

Specified by:
getStatus in interface Handle
Returns:
the internal status code of the Handle.
See Also:
setStatus(int)

setStatus

public void setStatus(int status)
Set the status of the Handle and a status message. If the status changes from blocking to non blocking then the Selector.handleStatusChanged(org.jumpi.spi.Handle) method is called.

Specified by:
setStatus in interface Handle
Parameters:
status - the internal status of the Handle.
See Also:
getStatus(), setStatus(int), Selector.handleStatusChanged(org.jumpi.spi.Handle)

setStatus

public void setStatus(int status,
                      java.lang.String statusMessage)
Set the status of the Handle and a status message. If the status changes from blocking to non blocking then the Selector.handleStatusChanged(org.jumpi.spi.Handle) method must be called.

Specified by:
setStatus in interface Handle
Parameters:
status - the internal status of the Handle.
statusMessage - the internal status message of the Handle.
See Also:
getStatus(), setStatus(int), Selector.handleStatusChanged(org.jumpi.spi.Handle)

setStatus

public void setStatus(int status,
                      java.lang.Object msg)
Set the status of the Handle and a message received. If the status changes from blocking to non blocking then the Selector.handleStatusChanged(org.jumpi.spi.Handle) method must be called.

Parameters:
status - the internal status of the Handle.
msg - the message to be sent or received.
See Also:
getStatus(), setStatus(int), Selector.handleStatusChanged(org.jumpi.spi.Handle)

setStatus

public void setStatus(int status,
                      java.lang.String statusMessage,
                      java.lang.Object msg)
Set the status of the Handle and a message and status message. If the status changes from blocking to non blocking then the Selector.handleStatusChanged(org.jumpi.spi.Handle) method must be called.

Parameters:
status - the internal status of the Handle.
statusMessage - the internal status message of the Handle.
msg - the message to be sent or received.
See Also:
getStatus(), setStatus(int), Selector.handleStatusChanged(org.jumpi.spi.Handle)

getStatusMessage

public java.lang.String getStatusMessage()
Return the current status message.

Specified by:
getStatusMessage in interface Handle
Returns:
the current status message.
See Also:
setStatusMessage(java.lang.String), setStatus(int,String,Object)

setStatusMessage

public void setStatusMessage(java.lang.String statusMessage)
Set the current status message.

Specified by:
setStatusMessage in interface Handle
Parameters:
statusMessage - the current status message.
See Also:
getStatusMessage()

isNonBlocking

public boolean isNonBlocking()
Returns true when the Handle's status is non blocking, that is, getStatusCode() does NOT return STATUS_TRANSIENT, otherwise false.

Specified by:
isNonBlocking in interface Handle
Returns:
true when the status is non blocking, otherwise false.

isBlocking

public boolean isBlocking()
Returns true when the Handle's status is blocking, that is, getStatusCode() returns STATUS_TRANSIENT, otherwise false.

Specified by:
isBlocking in interface Handle
Returns:
true when the status is blocking, otherwise false.

getMessage

public java.lang.Object getMessage()
Return the message being sent or which has been received. Returns null if unavailable.

Specified by:
getMessage in interface Handle
Returns:
the message being sent or which has been received, or null if unavailable.
See Also:
setMessage(java.lang.Object), setStatus(int,Object)

setMessage

public void setMessage(java.lang.Object msg)
Set the message being sent or which has been received.

Specified by:
setMessage in interface Handle
Parameters:
msg - the message being sent or which has been received.
See Also:
getMessage()

getDestination

public Destination getDestination()
Gets the Destination to which a message is being sent or being received from.

Specified by:
getDestination in interface Handle
Returns:
the Destination to which a message is being sent or being received from.
See Also:
setDestination(org.jumpi.spi.Destination)

setDestination

public void setDestination(Destination dest)
Sets the Destination to which a message is being sent or being received from.

Specified by:
setDestination in interface Handle
Parameters:
dest - the Destination to which a message is being sent or being received from.
See Also:
getDestination()

getSender

public Destination getSender()
Get the Destination representation of the sender of a received message.

Specified by:
getSender in interface Handle
Returns:
the Destination representing a sender of a received message.
See Also:
setSender(org.jumpi.spi.Destination)

setSender

public void setSender(Destination sender)
Set the Destination which represents the sender of a received message.

Specified by:
setSender in interface Handle
Parameters:
sender - the Destination representing the sender of a received message.
See Also:
getSender()

getProperties

public java.util.Hashtable getProperties()
Returns additional information concerning the send or receive operation to the Jumpi client application. Guaranteed not to be the same Properties instance as that used in Jumpi.send() or Jumpi.recv(). These are properties set by the Jumpi implementation only and are implementation dependent.

Specified by:
getProperties in interface Handle
Returns:
implementation dependent properties concerning the send or receive operation.
See Also:
ensureProperties(), removeProperties()

ensureProperties

public void ensureProperties()
Ensure that there is a Hashtable for implementation specific Properties which will be returned to a Jumpi client application with getProperties(). A Jumpi implementation first ensures that Properties exist and then uses getProperties() to get them, and then modify them. Calling more than once has no effect. This mechanism allows lazy creation of Properties when needed, avoiding obligatory creation of empty containers.

Specified by:
ensureProperties in interface Handle
See Also:
getProperties(), removeProperties()

removeProperties

public void removeProperties()
Ensure that there are no implementation specific Properties which will be returned to a Jumpi client application with getProperties().

Specified by:
removeProperties in interface Handle
See Also:
getProperties(), ensureProperties()

setClientProperties

public void setClientProperties(java.util.Hashtable props)
Sets the read-only client properties as used in Jumpi.send() or Jumpi.recv(). Setting the client properties in a non blocking state has no effect unless it is being cleared. Client properties are automatically cleared when the Handle becomes non blocking.

Specified by:
setClientProperties in interface Handle
Parameters:
props - the read-only client properties.
See Also:
getClientProperties(), Jumpi.send(org.jumpi.Destination, java.lang.Object, org.jumpi.Selector, java.util.Hashtable), Jumpi.recv(org.jumpi.Destination, org.jumpi.Selector, java.util.Hashtable)

getClientProperties

public java.util.Hashtable getClientProperties()
Returns the read-only client properties as used in Jumpi.send() or Jumpi.recv() when blocking, otherwise null. The reference to the client Properties is removed as soon as a non blocking state is reached, to allow early garbage collection of possibly unused data.

Specified by:
getClientProperties in interface Handle
Returns:
the read-only client properties when the state is blocking, otherwise null.
See Also:
setClientProperties(java.util.Hashtable), Jumpi.send(org.jumpi.Destination, java.lang.Object, org.jumpi.Selector, java.util.Hashtable), Jumpi.recv(org.jumpi.Destination, org.jumpi.Selector, java.util.Hashtable)

cancel

public void cancel()
Immediately cancel the send or receive operation associated with the Handle. This entails delegating the cancel operation to the responsible Controller if there is one. The status of the Handle is STATUS_CANCEL regardless of whether the Controller actually cancels the operation or not.

Specified by:
cancel in interface Handle
See Also:
Controller.cancelSend(org.jumpi.spi.Destination, org.jumpi.spi.Handle), Controller.cancelRecv(org.jumpi.spi.Destination, org.jumpi.spi.Handle)

waitWhileBlocking

public void waitWhileBlocking()
Wait for an unlimited time until the status of the Handle becomes non blocking. Thread interruption does not cause a waiting thread to return.

Specified by:
waitWhileBlocking in interface Handle

waitWhileBlocking

public void waitWhileBlocking(long timeout)
Wait for a limited time until the status of the Handle becomes non blocking.

Specified by:
waitWhileBlocking in interface Handle
Parameters:
timeout - maximum waiting time in milliseconds before returning if the status does not change to non blocking.

isSendHandle

public boolean isSendHandle()
Whether the Handle is associated with a send operation or not.

Specified by:
isSendHandle in interface Handle
Returns:
true if the Handle is associated with a send operation otherwise false.
See Also:
isRecvHandle()

isRecvHandle

public boolean isRecvHandle()
Whether the Handle is associated with a receive operation or not.

Specified by:
isRecvHandle in interface Handle
Returns:
true if the Handle is associated with a receive operation otherwise false.
See Also:
isSendHandle()

setController

public void setController(Controller controller)
Set the Controller instance responsible for the Handle. An Handle must have a reference to its responsible Controller since the cancel operation must inform the Controller, which then takes further action.

Specified by:
setController in interface Handle
Parameters:
controller - the responsible Controller.
See Also:
Handle.cancel(), getController()

getController

public Controller getController()
Get the Controller instance responsible for the Handle.

Specified by:
getController in interface Handle
Returns:
the Controller responsible for the Handle.
See Also:
setController(org.jumpi.spi.component.Controller)

assertStatusCode

public void assertStatusCode(int status,
                             java.lang.String errorMessage)
                      throws java.lang.Exception
Throw an Exception with the provided error message if the status code does not match the provided value. A convenience function. The Handle's getStatusMessage is appended to the errorMessage if there is any.

Specified by:
assertStatusCode in interface Handle
Parameters:
status - the Status code required for return without throwing an Exception.
errorMessage - the error message to use in the Exception thrown if any.
Throws:
java.lang.Exception - if status != getStatusMessage.

Jumpi v1.2.0

Copyright 2003, Peter Jonathan Klauser.