org.jumpi
Interface Handle

All Known Subinterfaces:

Handle

All Known Implementing Classes:

HandleImpl

public interface Handle

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.

Sending a message to a Destination by Jumpi.send(org.jumpi.Destination, java.lang.Object, org.jumpi.Selector, java.util.Hashtable) returns a sending Handle. Receiving a message from a Destination by Jumpi.recv(org.jumpi.Destination, org.jumpi.Selector, java.util.Hashtable) returns a receiving Handle. For receiving handles, the methods getMessage() is used to get a received message, and getSender() is used to get the Destination of the sender. The methods return undefined values for sending Handles. The method getMessage() does not return the sent message used in Jumpi.send() since this is dangerous, since garbage collection of the message would depend on the reference to it from the Handle.

The status of the message sending and receiving can be tracked by the Jumpi client application using getStatusCode(). The status of an Handle can be either blocking or non blocking. Handles are blocking when their status is STATUS_TRANSIENT. Blocking means that Jumpi is still in the process of sending or receiving using the Handle. The status is initially blocking until either success or failure at sending or receiving or until the sending or receiving operation is cancelled. A Jumpi client application can use waitWhileBlocking() to wait for transitions from a blocking to a non blocking state.

The blocking status of an Handle can be inquired by isBlocking() or isNonBlocking() for convenience. A blocking sending or receiving operation can be cancelled through the Handle by the cancel() method. Blocking send operations and more often receive operations which are not necessary should be cancelled. This allows Jumpi implementation to do cleanup work and free resources.

The following is a list of states:

• Status.STATUS_TRANSIENT means that sending or receiving is still in progress. The methods getMessage() and getSender() return undefined values.
• Status.STATUS_SUCCESS, sending or receiving is successfully completed. Furthermore when the Handle a receiving Handle, then getMessage() returns the received message, and getSender() returns the sender of the message.
• Status.STATUS_FAILURE, sending or receiving is unsuccessful. getStatusMessage() always gives a description of the failure. The methods getMessage() and getSender() return undefined values.
• Status.STATUS_CANCELLED, sending or receiving has been cancelled. The message may have been sent successfully or not at all, if a sending Handle is cancelled. A message may or may not have been received when a receiving Handle is cancelled.

Handles can be added and removed from Selectors with Selector.addHandle(org.jumpi.Handle) and Selector.removeHandle(org.jumpi.Handle) respectively. Selectors can be used to notify a Jumpi client application when the status of any of the registered Handles transition from blocking to non blocking status.

A Jumpi client application can be provided implementation dependent information about the associated send or receive operation through the getProperties() method. The Properties are unrelated to the Jumpi send or Jumpi receive properties. Those provide the Jumpi implementation additional information for sending or receiving. The Properties provided by getProperties() provide the Jumpi client application with additional information. The separation is necessary to provide safety when multiple receive or send operations change Properties.

Method Summary

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() Cancel the sending or receiving operation associated with the Handle.
Destination	getDestination() Return the Destination to which the message is sent for sending Handles, and the Destination from which messages are received with receiving Handles.
java.lang.Object	getMessage() Return a received message.
java.util.Hashtable	getProperties() Returns additional information concerning the send or receive operation to the Jumpi client application.
Destination	getSender() Return the sender of the received message.
int	getStatusCode() Returns the current Status of the Handle.
java.lang.String	getStatusMessage() Returns further textual information regarding the state of the Handle.
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 receiving operation.
boolean	isSendHandle() Whether the Handle is associated with a sending operation.
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.

Method Detail

getMessage

public java.lang.Object getMessage()

Return a received message. The return value is undefined unless the Handle is a receiving Handle, and the status returned by getStatusCode() is STATUS_SUCCESS. This method never blocks, eventhough the terminology of blocking and non blocking status might suggest so.

The class of the message received is implementation dependent. The ordering of the message with respect to other messages is implementation dependent. In fact all messaging delivery guarantees are implementation dependent.

Returns:

a received message.

getSender

public Destination getSender()

Return the sender of the received message. The return value is undefined unless the Handle is a receiving Handle and the status returned by getStatusCode() is STATUS_SUCCESS.

Returns:

the sender of the received message.

getDestination

public Destination getDestination()

Return the Destination to which the message is sent for sending Handles, and the Destination from which messages are received with receiving Handles. Identical to the Destinations used in Jumpi.send() and Jumpi.recv().

Returns:

the sending or receiving Destination

getProperties

public java.util.Hashtable getProperties()

Returns additional information concerning the send or receive operation to the Jumpi client application. Guarranteed 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.

Returns:

implementation dependent properties concerning the send or receive operation.

getStatusCode

public int getStatusCode()

Returns the current Status of the Handle.

Returns:

the current Status of the Handle.

getStatusMessage

public java.lang.String getStatusMessage()

Returns further textual information regarding the state of the Handle. The method is only obliged to give a meaningful value when the getStatusCode() returns STATUS_FAILURE.

Returns:

further textual information regarding the state of the Handle.

isNonBlocking

public boolean isNonBlocking()

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

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.

Returns:

true when the status is blocking, otherwise false.

cancel

public void cancel()

Cancel the sending or receiving operation associated with the Handle. The cancel only has effect if the current status is blocking. Cancel allows Jumpi implementations to free resources when pending asynchronous send or receive operations when not needed by a Jumpi client application.

It is implementation dependent how cancellation takes place and if operations can be cancelled once started. A cancelled send may or may not have been transmitted successfully. A cancelled recv may or may not have received a message successfully.

Cancellation is not obliged to interrupt blocking operating system send and receive calls, and is not a means of unblocking distributed deadlock.

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.

waitWhileBlocking

public void waitWhileBlocking(long timeout)

Wait for a limited time until the status of the Handle becomes non blocking.

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 sending operation. Invariant.

Returns:

true if associated with a sending operation, false if associated with a receiving operation.

isRecvHandle

public boolean isRecvHandle()

Whether the Handle is associated with a receiving operation. Invariant.

Returns:

true if associated with a receiving operation, false if associated with a sending operation.

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.

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.