Project JXTA

net.jxta.endpoint
Interface Messenger

All Superinterfaces:
SimpleSelectable
All Known Implementing Classes:
AbstractMessenger, AsyncChannelMessenger, ChannelMessenger, ThreadedMessenger

public interface Messenger
extends SimpleSelectable

A Messenger is used to send messages to a destination. This interface specifies the allowed observable states for a messenger. (fine grain). This serves to normalize the state machines of the various messenger implementations and allows for more meaningfull diagnostics. Implementations may use substates by adding high order bits, but these should never be reported by the public state observation methods. Most implementations will not use all these states.

Each valid state is represented by a integer that is a power of 2.

The (coarse grain) constants: USABLE, RESOLVED, TERMINAL, IDLE, SATURATED represent meaningfull partitions of the space of states.

The value of each constant is the bitwise OR of the states for which a given predicate is true: usable or not, confirmed or not, etc. Therefore the value of predicate p in state s is (s & p)!=0.

These particular predicates are chosen so that they have a relevant truth value for all states. Therefore the bitwise negation of the corresponding constants represents the obvious: ~USABLE really lists all states that mean "not USABLE".

These constants may be combined by bit logic operators to represent more predicates. waitState(int, long) accepts such values as a parameter.

Applications should depend on the coarse grain constants, rather than those denoting descreet states.

See Also:
EndpointService, SimpleSelector, EndpointAddress, Message, MessengerState

Nested Class Summary
 
Nested classes/interfaces inherited from interface net.jxta.util.SimpleSelectable
SimpleSelectable.IdentityReference
 
Field Summary
static int ANYSTATE
          The bitwise OR of all valid states.
static int BREAKING
          Failed to re-establish connection.
static int BROKEN
          Failed to re-establish connection.
static int CLOSED
          Closed as requested.
static int CLOSING
          Currently sending messages.
static int CONNECTED
          Currently connected.
static int DISCONNECTED
          Currently not connected.
static int DISCONNECTING
          Breaking established connection for expedite closure.
static int IDLE
          Composite state.
static int RECONCLOSING
          Trying to re-establish connection.
static int RECONNECTING
          Currenly trying to re-establish connection.
static int RECONSATURATED
          Currently trying to re-establish connection.
static int RESOLCLOSING
          Attempting initial connection.
static int RESOLPENDING
          Initial connection is being attempted.
static int RESOLSATURATED
          Initial connection is being attempted.
static int RESOLVED
          Composite state.
static int RESOLVING
          Initial connection is being attempted.
static int SATURATED
          Composite state.
static int SENDING
          Currently connected and sending messages.
static int SENDINGSATURATED
          Currently sending messages.New messages may not be submitted at this time.
static int TERMINAL
          Composite state.
static int UNRESOLVABLE
          Failed to establish initial connection.
static int UNRESOLVED
          No message was ever submitted for sending.
static int UNRESOLVING
          Failed to establish initial connection.
static int USABLE
          Composite state.
 
Method Summary
 void close()
          Close this messenger after processing any pending messages.
 void flush()
          Makes sure that all outstanding messages have been processed; successfully or not.
 Messenger getChannelMessenger(PeerGroupID redirection, String service, String serviceParam)
          If applicable, returns another messenger that will send messages to the same destination address than this one, but with the specified default service and serviceParam, possibly rewriting addresses to ensure delivery through the specified redirection.
 EndpointAddress getDestinationAddress()
          Returns the destination of this messenger.
 EndpointAddress getDestinationAddressObject()
          Returns the internal EndpointAddress object of the destination of the user.
 EndpointAddress getLogicalDestinationAddress()
          Returns the logical destination of this messenger.
 long getMTU()
          Returns the maximum message size that this messenger can handle.
 int getState()
          Returns the current state.
 boolean isClosed()
          Deprecated. Use (getState() & USABLE == 0) instead.
 boolean isIdle()
          Deprecated. no longer relevant and always false. This notably is not equivalent to the IDLE state.
 boolean isSynchronous()
          Deprecated. all messengers are asynchronous, and the sendMessageB(net.jxta.endpoint.Message, java.lang.String, java.lang.String) method is always blocking.
 void resolve()
          Force the messenger to start resolving if it is not resolved yet.
 boolean sendMessage(Message msg)
          Sends a message to the destination specified at construction as if by invoking sendMessage(msg, null, null)

This is a legacy method.

 boolean sendMessage(Message msg, String service, String serviceParam)
          Sends a message to the destination specified at construction.
 void sendMessage(Message msg, String service, String serviceParam, OutgoingMessageEventListener listener)
          Deprecated. This legacy method is being phased out. Prefer sendMessageN(net.jxta.endpoint.Message, java.lang.String, java.lang.String) to send messages in a non blocking fashion.
 void sendMessageB(Message msg, String service, String serviceParam)
          Simple sending: blocks until the message was accepted for sending or the messenger is not USABLE; whichever occurs first.
 boolean sendMessageN(Message msg, String service, String serviceParam)
          Sends a message to the destination specified at construction.
 int waitState(int wantedStates, long timeout)
          Blocks unless and until the current state is or has become one of the desired values.
 
Methods inherited from interface net.jxta.util.SimpleSelectable
getIdentityReference, itemChanged, register, unregister
 

Field Detail

UNRESOLVED

static final int UNRESOLVED
No message was ever submitted for sending. No connection was ever attempted.

See Also:
Constant Field Values

RESOLVING

static final int RESOLVING
Initial connection is being attempted. No message is pending.

See Also:
Constant Field Values

CONNECTED

static final int CONNECTED
Currently connected. No message is pending (being sent implies pending).

See Also:
Constant Field Values

DISCONNECTED

static final int DISCONNECTED
Currently not connected. No message is pending.

See Also:
Constant Field Values

RESOLPENDING

static final int RESOLPENDING
Initial connection is being attempted. Messages are pending.

See Also:
Constant Field Values

RESOLSATURATED

static final int RESOLSATURATED
Initial connection is being attempted. Messages are pending. New messages may not be submitted at this time.

See Also:
Constant Field Values

SENDING

static final int SENDING
Currently connected and sending messages.

See Also:
Constant Field Values

SENDINGSATURATED

static final int SENDINGSATURATED
Currently sending messages.New messages may not be submitted at this time.

See Also:
Constant Field Values

RECONNECTING

static final int RECONNECTING
Currenly trying to re-establish connection. Messages are pending.

See Also:
Constant Field Values

RECONSATURATED

static final int RECONSATURATED
Currently trying to re-establish connection. New messages may not be submitted at this time.

See Also:
Constant Field Values

RESOLCLOSING

static final int RESOLCLOSING
Attempting initial connection. Close has been requested. Messages are pending. New messages may no longer be submitted.

See Also:
Constant Field Values

CLOSING

static final int CLOSING
Currently sending messages. Close has been requested. New messages may no longer be submitted.

See Also:
Constant Field Values

RECONCLOSING

static final int RECONCLOSING
Trying to re-establish connection. Close has been requested. Messages are pending. New messages may no longer be submitted.

See Also:
Constant Field Values

UNRESOLVING

static final int UNRESOLVING
Failed to establish initial connection. Pending messages are being rejected. New messages may no longer be submitted.

See Also:
Constant Field Values

BREAKING

static final int BREAKING
Failed to re-establish connection. Pending messages are being rejected. New messages may no longer be submitted.

See Also:
Constant Field Values

DISCONNECTING

static final int DISCONNECTING
Breaking established connection for expedite closure. Pending messages are being rejected. New messages may no longer be submitted.

See Also:
Constant Field Values

UNRESOLVABLE

static final int UNRESOLVABLE
Failed to establish initial connection. New messages may no longer be submitted. State will never change again.

See Also:
Constant Field Values

BROKEN

static final int BROKEN
Failed to re-establish connection. New messages may no longer be submitted. State will never change again.

See Also:
Constant Field Values

CLOSED

static final int CLOSED
Closed as requested. All pending messages could be sent. New messages may no longer be submitted. State will never change again.

See Also:
Constant Field Values

ANYSTATE

static final int ANYSTATE
The bitwise OR of all valid states.

See Also:
Constant Field Values

USABLE

static final int USABLE
Composite state.

Not known to be broken. Messenger may be used to send messages. Viability has not been evaluated yet. This is the most usefull predicate to applications. USABLE means that it is reasonable to try and send a message.

See Also:
Constant Field Values

RESOLVED

static final int RESOLVED
Composite state.

Messenger was once resolved. Messenger was at least once proven viable. Current usability is not asserted. For example a messenger may be found to be in a TERMINAL state, but also be in a RESOLVED state. Thus proving that the destination of the messenger is sometimes valid.

See Also:
Constant Field Values

TERMINAL

static final int TERMINAL
Composite state.

Messenger has terminated its usefull life. State will never change any more.

See Also:
Constant Field Values

IDLE

static final int IDLE
Composite state.

Any message that may have been submitted in the past has been either sent or failed already. If a messenger is in a state IDLE & RESOLVED & USABLE, then the expected delay in sending a message is minimal.

See Also:
Constant Field Values

SATURATED

static final int SATURATED
Composite state.

This messenger cannot take new messages for now. All available buffering space is occupied. Note that only the usable states can be saturated. Once a messenger is in the process of terminating and thus takes no new messages anyway, it no-longer shows as saturated.

See Also:
Constant Field Values
Method Detail

getState

int getState()
Returns the current state.

Returns:
one of the legal descreet state values.

waitState

int waitState(int wantedStates,
              long timeout)
              throws InterruptedException
Blocks unless and until the current state is or has become one of the desired values. The observable states are guaranteed to be represented by a single bit. Multiple desired values may be specified by passing them ORed together.

This class defines the list of constants that may be used and how these may be combined.

Note that the state can change as soon as this method returns, so any observation is only an indication of the past. Synchronizing on the object itself has no other effect than interfering with other threads doing the same. Obviously, certain transitions cannot happen unless a new message is submitted. So unless another thread is using a messenger, it is safe to assume that a non-saturated messenger will not become saturated spontaneously. Note that messengers returned by different endpoint service interface objects (what PeerGroup.getEndpointService() returns) are different. However a given endpoint interface object will return an existing messenger to the same exact destination if there is a USABLE one. With an unshared messenger, one can wait for any change with waitState(~getState(), 0);.

Note that it is advisable to always OR the desired states with TERMINAL, unless being blocked passed the messenger termination is an acceptable behaviour.

Examples:

Ensure that the messenger can take more messages (or is UNUSABLE): waitState(~SATURATED)

Ensure that all submitted messages have been sent: waitState( TERMINAL | IDLE )

Ensure that the messenger is already resolved and can take more messages: waitState(TERMINAL | (RESOLVED & ~SATURATED) )

Parameters:
wantedStates - The binary OR of the desired states.
timeout - How long to wait. A timeout of 0 means no time limit.
Returns:
The desired state that was reached or the current state when time ran out.
Throws:
InterruptedException - If the invoking thread was interrupted before the condition was realized.

isClosed

boolean isClosed()
Deprecated. Use (getState() & USABLE == 0) instead.

Returns true if this messenger is closed and no longer accepting messages to be sent. The messenger should be discarded.

Returns:
true if this messenger is closed, otherwise false.

isIdle

boolean isIdle()
Deprecated. no longer relevant and always false. This notably is not equivalent to the IDLE state.

Tells whether this messenger may be worth closing.

Returns:
true if the messenger is idle otherwise false.

isSynchronous

boolean isSynchronous()
Deprecated. all messengers are asynchronous, and the sendMessageB(net.jxta.endpoint.Message, java.lang.String, java.lang.String) method is always blocking.

Returns true if the sendMessage methods of this messenger are fully synchronous.


getDestinationAddress

EndpointAddress getDestinationAddress()
Returns the destination of this messenger. The returned EndpointAddress is a clone and can be freely used by the caller.

Returns:
EndpointAddress the destination address of this messenger
See Also:
getLogicalDestinationAddress()

getDestinationAddressObject

EndpointAddress getDestinationAddressObject()
Returns the internal EndpointAddress object of the destination of the user. Changing the content of the object may have unpredictable consequence on the behavior of the EndpointMessenger. This method is intended to be used for applications that requires to have weak or soft reference to an EndpointMessenger: the returned Endpoint Address object will be unreferenced when this messenger will finalize.

Returns:
EndpointAddress the destination address of this messenger
See Also:
getDestinationAddress()

getLogicalDestinationAddress

EndpointAddress getLogicalDestinationAddress()
Returns the logical destination of this messenger. This may be a different address than is returned by getDestinationAddress and refers to the entity which is located at the destination address.

By analogy, a telephone number would be the destination address, and the owner of that telephone number would be the logical destination. Each logical destination may be known by one or more destination addresses.

Returns:
EndpointAddress the logical destination address of this messenger.
See Also:
getDestinationAddress()

getMTU

long getMTU()
Returns the maximum message size that this messenger can handle. That limit refers to the cummulative size of application level elements. The various sendMessage will refuse to send messages that exceed this limit.

Returns:
the limit.

getChannelMessenger

Messenger getChannelMessenger(PeerGroupID redirection,
                              String service,
                              String serviceParam)
If applicable, returns another messenger that will send messages to the same destination address than this one, but with the specified default service and serviceParam, possibly rewriting addresses to ensure delivery through the specified redirection. This is not generaly usefull to applications and most messengers will return null. This method is needed by the EndpointService when interacting with Messengers provided by Transport modules. If you are not implementing a Transport module, then you can ignore this method. Important: The channel so obtained is not configured to support the sendMessage(Message, String, String, OutgoingMessageEventListener) legacy method. If use of this method is desired, ChannelMessenger.setMessageWatcher(net.jxta.endpoint.ListenerAdaptor) must be used first.

Parameters:
redirection - The requested redirection. The resulting channel messenger will use this to force delivery of the message only in the specified group (or possibly decendants, but not parents). If null the local group is assumed. This redirection is applied only to messages that are sent to a service name and service param that do not imply a group redirection.
service - The service to which the resulting channel will send messages, when they are not sent to a specified service.
serviceParam - The service parameter that the resulting channel will use to send messages, when no parameter is specified.
Returns:
a channelMessenger as specified.
See Also:
MessageSender.getMessenger(EndpointAddress, Object)

close

void close()
Close this messenger after processing any pending messages. This method is not blocking. Upon return, the messenger will be in one of the non USABLE states, which means that no message may be sent through it. Any other effect of this method, such as an underlying connection being closed, or all pending messages being processed, may be deferred indefinitely. When the messenger has completely processed the closure request, it will be in one of the TERMINAL states (which are also IDLE states). Therefore, if one is interrested in the outcome of the closure, one may wait for the messenger to be in a TERMINAL or IDLE state, and check which it is. CLOSED denotes success (all outstanding messages have been sent), as opposed to UNRESOLVABLE or BROKEN.


flush

void flush()
           throws IOException
Makes sure that all outstanding messages have been processed; successfully or not. This method waits unless and until the state of the messenger is an IDLE state. If the reached state is neither CLOSED or any USABLE state, then it throws an IOException. Else it returns silently.

If another thread keeps sending messages, this method may never return.

This method is deliberately simple. If a timeout needs to be provided, or if more detailed conditions are required, the waitState(int, long) and getState() methods should be used. For example :

 int myFlush(long notTooLong) {
   messenger.waitState(IDLE, notTooLong);
   if ((messenger.getState() & IDLE) == 0) return TOOLONG;
   if ((messenger.getState() & USABLE) != 0) return FLUSHED;
   if (messenger.getState() == CLOSED) return CLOSEDANDFLUSHED;
   return BROKEN;
 }
 

Note: close() being asynchronous, it is valid to invoke flush() after close() as a form of synchronous variant of close(). If this messenger is not shared with any other thread, then invoking flush() before close is a more familiar means of achieving the same effect.

Throws:
IOException - This messenger failed before processing all outstanding messages successfully.

resolve

void resolve()
Force the messenger to start resolving if it is not resolved yet. Any attempt at sending a message has the same effect, but the message may fail as a result, depending upon the method used.


sendMessageB

void sendMessageB(Message msg,
                  String service,
                  String serviceParam)
                  throws IOException
Simple sending: blocks until the message was accepted for sending or the messenger is not USABLE; whichever occurs first. If a service name and service param are specified, they will replace those specified at construction for the purpose of sending this message only.

Error Handling:

WARNING: The Message object should not be reused or modified until completely processed. Concurrent modification of a message while a messenger is sending the message will produce incorrect and unpredictable results. If completion is not monitored, the message should never be reused. If necessary, a clone of the message may be provided to sendMessageB(net.jxta.endpoint.Message, java.lang.String, java.lang.String):

     messenger.sendMessageB( (Message) myMessage.clone(), theService, theParam );
 

There is no guarantee that a message successfully sent will actually be received.

Parameters:
service - Optionally replaces the service in the destination address. If null then the destination address's default service will be used. If the empty string ("") is used then no service is included in the destination address.
serviceParam - Optionally replaces the service param in the destination address. If null then the destination address's default service parameter will be used. If the empty string ("") is used then no service param is included in the destination address.
Throws:
IOException - Thrown if the message cannot be sent.

sendMessageN

boolean sendMessageN(Message msg,
                     String service,
                     String serviceParam)
Sends a message to the destination specified at construction. If a service name and service param are specified, they will replace those specified at construction for the purpose of sending this message only.

This method is identical to sendMessage(Message, String, String), except that it does not throw an exception. The invoker has to retrieve a detailed status from the message if needed.

Error Handling:

WARNING: The Message object should not be reused or modified until completely processed. Concurrent modification of a message while a messenger is sending the message will produce incorrect and unpredictable results. If completion is not monitored, the message should never be reused. If necessary, a clone of the message may be provided to sendMessageN(net.jxta.endpoint.Message, java.lang.String, java.lang.String):

     messenger.sendMessageN( (Message) myMessage.clone(), theService, theParam );
 

There is no guarantee that a message successfully sent will actually be received.

Parameters:
msg - The message to send.
service - Optionally replaces the service in the destination address. If null then the destination address's default service will be used. If the empty string ("") is used then no service is included in the destination address.
serviceParam - Optionally replaces the service param in the destination address. If null then the destination address's default service parameter will be used. If the empty string ("") is used then no service param is included in the destination address.
Returns:
boolean true if the message has been accepted for sending, otherwise false.

sendMessage

boolean sendMessage(Message msg)
                    throws IOException
Sends a message to the destination specified at construction as if by invoking sendMessage(msg, null, null)

This is a legacy method. Modern code should prefer the other methods and select messages. If a listener API is preferred, it is possible to use a ListenerAdaptor object explicitly to have a listener called.

Parameters:
msg - The message to send.
Returns:
boolean true if the message has been accepted for sending, otherwise false.
Throws:
IOException - Thrown if the message cannot be sent.

sendMessage

boolean sendMessage(Message msg,
                    String service,
                    String serviceParam)
                    throws IOException
Sends a message to the destination specified at construction. If a service name and service param are specified, they will replace those specified at construction for the purpose of sending this message only.

Error Handling:

WARNING: The Message object should not be reused or modified until completely processed. Concurrent modification of a message while a messenger is sending the message will produce incorrect and unpredictable results. If completion is not monitored, the message should never be reused. If necessary, a clone of the message may be provided to sendMessage:

     messenger.sendMessage( (Message) myMessage.clone(), theService, theParam );
 

There is no guarantee that a message successfully sent will actually be received.

Limitation: using this method along with SimpleSelector.select() on the same message may occasionaly cause some errors to not be thrown. Prefer sendMessageN(net.jxta.endpoint.Message, java.lang.String, java.lang.String) when using SimpleSelector.select().

This is a legacy method. Modern code should prefer the other methods and select messages. If a listener API is preferred, it is possible to use a ListenerAdaptor object explicitly to have a listener called.

Parameters:
msg - The message to send.
service - Optionally replaces the service in the destination address. If null then the destination address's default service will be used. If the empty string ("") is used then no service is included in the destination address.
serviceParam - Optionally replaces the service param in the destination address. If null then the destination address's default service parameter will be used. If the empty string ("") is used then no service param is included in the destination address.
Returns:
boolean true if the message has been accepted for sending, otherwise false.
Throws:
IOException - Thrown if the message cannot be sent.

sendMessage

void sendMessage(Message msg,
                 String service,
                 String serviceParam,
                 OutgoingMessageEventListener listener)
Deprecated. This legacy method is being phased out. Prefer sendMessageN(net.jxta.endpoint.Message, java.lang.String, java.lang.String) to send messages in a non blocking fashion.

Sends a message to the destination specified at construction. If a service name and service param are specified, they will replace those specified at construction for the purpose of sending this message only.

WARNING: The Message object should not be reused or modified until the message has been fully processed. Concurrent modification of a message while a messenger is sending the message will produce incorrect and unpredictable results. If a listener is provided it is invoked after the message is considered fully processed. However it is recommended not to reuse or otherwise modify a messages after sending it. If necessary, a clone of the message may be provided to sendMessage:

     messenger.sendMessage( (Message) myMessage.clone() );
 

Error Handling:

As with all sendMessage methods, success is not a guarantee that the message will actually be received.

This is a legacy method. Modern code should prefer the other methods and select messages. If a listener API is preferred, it is possible to use a ListenerAdaptor object explicitly to have a listener called.

Parameters:
msg - The message to send.
service - Optionally replaces the service in the destination address. If null then the destination address's default service will be used. If the empty string ("") is used then no service is included in the destination address.
serviceParam - Optionally replaces the service param in the destination address. If null then the destination address's default service parameter will be used. If the empty string ("") is used then no service param is included in the destination address.
listener - listener for events about this message or null if no notification is desired.
Throws:
UnsupportedOperationException - If this messenger is not a channel or was not given a ListenerAdaptor. (all messengers obtained through EndpointService.getMessenger(net.jxta.endpoint.EndpointAddress, java.lang.Object) are configured properly.

JXTA J2SE