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.