org.jumpi.spi
Interface Handle

All Superinterfaces:

Handle

All Known Implementing Classes:

HandleImpl

public interface Handle

extends Handle

A service provider Handle interface extends the org.jumpi.Handle interface with extended information and control functions.

Method Summary

void	addSelector(Selector selector) Add the Selector to the list of Selectors to which the Handle belongs.
void	ensureProperties() Ensure that there is a Hashtable for implementation specific Properties which will be returned to a Jumpi client application with Handle.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.
int	getStatus() Get the internal status code of the Handle.
void	removeProperties() Ensure that there are no implementation specific Properties which will be returned to a Jumpi client application with Handle.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) Set the Destination of the Handle.
void	setMessage(java.lang.Object message) Set the message associated with the Handle.
void	setSender(Destination sender) Set the Destination representing the sender of the message for receiving operations.
void	setStatus(int status) Set the internal status of the Handle.
void	setStatus(int status, java.lang.String statusMessage) Set the status of the Handle and a status message.
void	setStatusMessage(java.lang.String statusMessage) Set the status message of the Handle.

Methods inherited from interface org.jumpi.Handle

assertStatusCode, cancel, getDestination, getMessage, getProperties, getSender, getStatusCode, getStatusMessage, isBlocking, isNonBlocking, isRecvHandle, isSendHandle, waitWhileBlocking, waitWhileBlocking

Method Detail

setStatus

public void setStatus(int status)

Set the internal status of the Handle. If the status changes from blocking to non blocking, then the Selector.handleStatusChanged(org.jumpi.spi.Handle) method must be called. All status codes which are not STATUS_SUCCESS, STATUS_FAILURE or STATUS_CANCELLED are considered blocking and are signified by STATUS_TRANSIENT with the return of getStatusCode().

Parameters:

status - the internal status of the Handle.

See Also:

getStatus(), Handle.getStatusCode(), 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.

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)

getStatus

public int getStatus()

Get the internal status code of the Handle.

Returns:

the internal status code of the Handle.

See Also:

setStatus(int)

setStatusMessage

public void setStatusMessage(java.lang.String statusMessage)

Set the status message of the Handle.

Parameters:

statusMessage - the status message.

setMessage

public void setMessage(java.lang.Object message)

Set the message associated with the Handle. For a send operation, the message is the message being sent by the Jumpi client application. For a receive operation, the message is the message which has been received.

Parameters:

message - the message being sent, or which has been received.

See Also:

Handle.getMessage()

setDestination

public void setDestination(Destination dest)

Set the Destination of the Handle. For a send operation, this is the Destination to which the message is to be sent. For a receive operation, this is the Destination from which to receive the message.

Parameters:

dest - the Destination to send a message to, or receive from.

setSender

public void setSender(Destination sender)

Set the Destination representing the sender of the message for receiving operations.

Parameters:

sender - the sender of the message.

See Also:

Handle.getSender()

ensureProperties

public void ensureProperties()

Ensure that there is a Hashtable for implementation specific Properties which will be returned to a Jumpi client application with Handle.getProperties(). A Jumpi implementation first ensures that Properties exist and then uses Handle.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.

See Also:

removeProperties()

removeProperties

public void removeProperties()

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

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.

Parameters:

props - the read-only client properties as used in Jumpi.send() or Jumpi.recv().

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.

Returns:

the read-only client properties as used in Jumpi.send() or Jumpi.recv() when 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)

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.

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.

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)

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.

Parameters:

controller - the responsible Controller.

See Also:

Handle.cancel(), getController()

getController

public Controller getController()

Get the Controller instance responsible for the Handle.

Returns:

the Controller responsible for the Handle.

See Also:

setController(org.jumpi.spi.component.Controller)