|
JXTA | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Messenger
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 meaningful 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 meaningful 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 discrete states.
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
Currently 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()
Deprecated. EndpointAddress is now immutable which means that this result is the same as getDestinationAddress() . This method will be
eventually removed. |
EndpointAddress |
getLogicalDestinationAddress()
Returns the logical destination of this messenger. |
long |
getMTU()
Returns the maximum message size that this messenger can be used to send. |
int |
getState()
Returns the current state. |
boolean |
isClosed()
Returns true if this messenger is closed and no longer
accepting messages to be sent. |
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 sendMessage(msg, null, null) |
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)
Sends a message to the destination specified at construction. |
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 |
---|
static final int UNRESOLVED
static final int RESOLVING
static final int CONNECTED
static final int DISCONNECTED
static final int RESOLPENDING
static final int RESOLSATURATED
static final int SENDING
static final int SENDINGSATURATED
static final int RECONNECTING
static final int RECONSATURATED
static final int RESOLCLOSING
static final int CLOSING
static final int RECONCLOSING
static final int UNRESOLVING
static final int BREAKING
static final int DISCONNECTING
static final int UNRESOLVABLE
static final int BROKEN
static final int CLOSED
static final int ANYSTATE
static final int USABLE
static final int RESOLVED
static final int TERMINAL
static final int IDLE
IDLE & RESOLVED & USABLE
, then the expected delay in sending a message
is minimal.
static final int SATURATED
Method Detail |
---|
int getState()
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 include TERMINAL
as part
of the desired states with unless being blocked past 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
- The maximum number of milliseconds to wait. A timeout of 0 means no time limit.
InterruptedException
- If the invoking thread was interrupted before the condition was realized.boolean isClosed()
true
if this messenger is closed and no longer
accepting messages to be sent. This is a shortcut for
(getState() & USABLE == 0)
. Once closed, a messenger should be
discarded.
true
if this messenger is closed, otherwise false
.@Deprecated boolean isIdle()
IDLE
state.
true
if the messenger is idle otherwise false
.@Deprecated 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.
EndpointAddress getDestinationAddress()
getLogicalDestinationAddress()
@Deprecated EndpointAddress getDestinationAddressObject()
getDestinationAddress()
. This method will be
eventually removed.
getDestinationAddress()
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()
long getMTU()
sendMessage()
variants will refuse to send messages
that exceed this limit.
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 descendents, 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)
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 interested 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
.
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.void resolve()
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 outstanding 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.
msg
- the messageservice
- 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.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 outstanding 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
.boolean sendMessage(Message msg) throws IOException
sendMessage(msg, null, null)
msg
- The message to send.
true
if the message has been accepted for sending, otherwise false
.
IOException
- Thrown if the message cannot be sent.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 outstanding 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 occasionally
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.
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.void sendMessage(Message msg, String service, String serviceParam, OutgoingMessageEventListener listener)
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 outstanding messages have been processed without this messenger detecting an error.null
listener, it provides very
little feedback to the invoker. A messenger should be abandoned 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.
|
JXSE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |