|
Project JXTA | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 & 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.
EndpointService
,
SimpleSelector
,
EndpointAddress
,
Message
,
MessengerState
Nested Class Summary |
Nested classes inherited from class 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 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
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 |
public static final int UNRESOLVED
public static final int RESOLVING
public static final int CONNECTED
public static final int DISCONNECTED
public static final int RESOLPENDING
public static final int RESOLSATURATED
public static final int SENDING
public static final int SENDINGSATURATED
public static final int RECONNECTING
public static final int RECONSATURATED
public static final int RESOLCLOSING
public static final int CLOSING
public static final int RECONCLOSING
public static final int UNRESOLVING
public static final int BREAKING
public static final int DISCONNECTING
public static final int UNRESOLVABLE
public static final int BROKEN
public static final int CLOSED
public static final int ANYSTATE
public static final int USABLE
public static final int RESOLVED
public static final int TERMINAL
public static final int IDLE
IDLE & RESOLVED & USABLE
, then the expected delay in sending a message
is minimal.
public static final int SATURATED
Method Detail |
public int getState()
public int waitState(int wantedStates, long timeout) throws InterruptedException
OR
ed 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) )
wantedStates
- The binary OR of the desired states.timeout
- How long to wait. A timeout of 0 means no time limit.
InterruptedException
- If the invoking thread was interrupted before the condition was realized.public boolean isClosed()
(getState() & USABLE == 0)
instead.
true
if this messenger is closed and no longer
accepting messages to be sent. The messenger should be discarded.
true
if this messenger is closed, otherwise
false
.public boolean isIdle()
IDLE
state.
true
if the messenger is idle otherwise false
.public boolean isSynchronous()
sendMessageB(net.jxta.endpoint.Message, java.lang.String, java.lang.String)
method is always blocking.
true
if the sendMessage
methods of
this messenger are fully synchronous.
public EndpointAddress getDestinationAddress()
getLogicalDestinationAddress()
public EndpointAddress getDestinationAddressObject()
getDestinationAddress()
public EndpointAddress getLogicalDestinationAddress()
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.
getDestinationAddress()
public long getMTU()
sendMessage
will refuse to send messages that exceed this limit.
public Messenger getChannelMessenger(PeerGroupID redirection, String service, String serviceParam)
sendMessage(Message, String, String,
OutgoingMessageEventListener)
legacy method. If use of this method is desired, ChannelMessenger.setMessageWatcher(net.jxta.endpoint.ListenerAdaptor)
must be used first.
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.
MessageSender.getMessenger(EndpointAddress, Object)
public void close()
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
.
public void flush() throws IOException
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.
IOException
- This messenger failed before processing all outstanding messages successfully.public void resolve()
public void sendMessageB(Message msg, String service, String serviceParam) throws IOException
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:
IOException
means that this message is invalid or that this messenger is now in one of the non USABLE
states and may no longer send new messages, and means that the message was not sent. The exact state of the
messenger may be obtained from the getState()
method. If no exception is thrown, the message is accepted for
sending and may or may not be fully processed.Message#getMessageProperty(Messenger.class)
will return an
object of class OutgoingMessageEvent
. Changes in a message's set of properties may be tracked by selecting the
message. If an exception was thrown, the message's properties will not be modified
IDLE
state that is either CLOSED
or a USABLE
state, then it may be inferred
that all outsdanding messages have been processed without this messenger detecting an error.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.
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.
IOException
- Thrown if the message cannot be sent.public boolean sendMessageN(Message msg, String service, String serviceParam)
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:
false
indicates that the message was not accepted to be sent. This may be due to
local resource limits being reached or to the messenger being in a state that is not USABLE
or to the message
being invalid. The exact cause of the failure can be retrieved from the message by using
Message.getMessageProperty(Messenger.class)
. If appropriate,
another attempt at sending the message, may be made after waiting for the congestion to clear (for example by using
waitState(int, long)
).true
indicates that the message was accepted for sending. It does not imply that
the message will be sent or that the destination will receive the message. There will be no indication by this method
of any errors in sending the message. If this messenger subsequently reaches an IDLE
state that is either CLOSED
or a USABLE
state, then it may be inferred that all outsdanding messages have been processed without this
messenger detecting an error.Message.getMessageProperty(Messenger.class)
will return an object of class OutgoingMessageEvent
. Changes in a message's set of properties may be tracked by
selecting the message.
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.
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.
true
if the message has been accepted for sending, otherwise false
.public boolean sendMessage(Message msg) throws IOException
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.
msg
- The message to send.
true
if the message has been accepted for sending, otherwise false
.
IOException
- Thrown if the message cannot be sent.public boolean sendMessage(Message msg, String service, String serviceParam) throws IOException
IOException
means that this message is invalid or that this messenger is now in one of the
non USABLE
states and may no longer send new messages, and that the message was not sent. The exact state of
the messenger may be obtained from the getState()
method.false
indicates that the message was not accepted to be sent. Usually this is due to
local resource limits being reached. If needed, another attempt at sending the message, may be made after waiting for the
congestion to clear (for example by using waitState(int, long)
).true
indicates that the message was accepted for sending. It does not imply that
the message will be sent or that the destination will receive the message. There will be no immediate indication of any
errors in sending the message. If this messenger subsequently reaches an IDLE
state that is either CLOSED
or a USABLE
state, then it may be inferred that all outsdanding messages have been processed without this
messenger detecting an error.Message.getMessageProperty(Messenger.class)
will return
an object of class OutgoingMessageEvent
. Changes in a message's set of properties may be tracked by selecting
the message.
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.
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.
true
if the message has been accepted for sending, otherwise false
.
IOException
- Thrown if the message cannot be sent.public void sendMessage(Message msg, String service, String serviceParam, OutgoingMessageEventListener listener)
sendMessageN(net.jxta.endpoint.Message, java.lang.String, java.lang.String)
to send messages in a non blocking fashion.
sendMessage
:
messenger.sendMessage( (Message) myMessage.clone() );
Error Handling:
OutgoingMessageEventListener.messageSendFailed(OutgoingMessageEvent)
or the OutgoingMessageEventListener.messageSendSucceeded(OutgoingMessageEvent)
method will be invoked:
messageSendFailed
will be invoked. The Throwable
object returned by the OutgoingMessageEvent.getFailure()
method of the passed event object will be null.USABLE
,
messageSendFailed
will be invoked. The Throwable
object returned by the OutgoingMessageEvent.getFailure()
method of the passed event object will reflect the messenger's condition.messageSendFailed
will be invoked. The
Throwable
object returned by the OutgoingMessageEvent.getFailure()
method of the passed event object
will reflect the origin of the failure.messageSendSucceeded
will be
invoked.IDLE
state that is either CLOSED
or a USABLE
state, then it
may be inferred that all outsdanding messages have been processed without this messenger detecting an error.null
listener, it provides very
little feedback to the invoker. A messenger should be abandonned once it is in one of the TERMINAL
states.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.
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.
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 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |