async.common
Interface MessageHandle

All Known Implementing Classes:
ASyncTCPMessageHandle, ASyncUDPMessageHandle

public interface MessageHandle

A handle to a Message object either currently or previously enqueued for delivery.

Author:
Michael Parker

Nested Class Summary
static class MessageHandle.MessageState
          The state of the Message.
 
Method Summary
 boolean cancel()
          Cancels the delivery of this message to the remote host, provided that it is still enqueued and is not in the process of being sent or has been sent already.
 long getEnqueuedTime()
          Returns the time, in milliseconds, at which this message was enqueued for delivery.
 MessageHandleListener getListener()
          Retrieves the listener for this message.
 Message getMessage()
          Returns the message for which this MessageHandle instance is a handle.
 MessageQueue getMessageQueue()
          Returns the message queue in which this message handle is or was once enqueued.
 int getQueuePosition()
          Returns the position of this message in whatever queue it belongs to, provided the state of this handle is ENQUEUED.
 long getSendingTime()
          Returns the time, in milliseconds, at which this message began sending.
 long getSentTime()
          Returns the time, in milliseconds, at which this message was sent in its entirety.
 MessageHandle.MessageState getState()
          Returns the state of this message.
 boolean moveBackward()
          Moves this message one position backward in the queue.
 boolean moveForward()
          Moves this message one position forward in the queue.
 MessageHandleListener setListener(MessageHandleListener mhl)
          Sets mhl as the listener on this message.
 

Method Detail

getState

MessageHandle.MessageState getState()
Returns the state of this message.

Returns:
the state of this message

getMessage

Message getMessage()
Returns the message for which this MessageHandle instance is a handle.

Returns:
the message itself

getMessageQueue

MessageQueue getMessageQueue()
Returns the message queue in which this message handle is or was once enqueued.

Returns:
the associated message queue

cancel

boolean cancel()
Cancels the delivery of this message to the remote host, provided that it is still enqueued and is not in the process of being sent or has been sent already.

Returns:
true if this message was enqueued but is now canceled, false otherwise

getQueuePosition

int getQueuePosition()
Returns the position of this message in whatever queue it belongs to, provided the state of this handle is ENQUEUED. The next message to be sent in a queue has a position of 0.

Returns:
the position of this message in its queue, or -1 if not enqueued

getEnqueuedTime

long getEnqueuedTime()
Returns the time, in milliseconds, at which this message was enqueued for delivery.

Returns:
the time this message was enqueued at

getSendingTime

long getSendingTime()
Returns the time, in milliseconds, at which this message began sending.

Returns:
the time this message began sending

getSentTime

long getSentTime()
Returns the time, in milliseconds, at which this message was sent in its entirety.

Returns:
the time this message was sent at, or -1 if it has not yet been sent

getListener

MessageHandleListener getListener()
Retrieves the listener for this message.

Returns:
the current listener for this message, or null if there is no listener

setListener

MessageHandleListener setListener(MessageHandleListener mhl)
Sets mhl as the listener on this message. The listener can later be retrieved via the getListener method. Only one listener may be set at a time; invoking this method causes any previous listener to be discarded. The current listener may be discarded by passing in null.

Parameters:
mhl - the new listener for this message
Returns:
the previous listener, if any; otherwise null

moveForward

boolean moveForward()
Moves this message one position forward in the queue. If this message is not enqueued, or is the first element in the queue, this method returns false.

Returns:
true if this message is moved forward in the queue, false otherwise

moveBackward

boolean moveBackward()
Moves this message one position backward in the queue. If this message is not enqueued, or is the last element in the queue, this method returns false.

Returns:
true if this message is moved backward in the queue, false otherwise