|
JXTA | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.jxta.util.AbstractSimpleSelectable
net.jxta.endpoint.AbstractMessenger
net.jxta.impl.endpoint.BlockingMessenger
public abstract class BlockingMessenger
This class is a near-drop-in replacement for the previous BlockingMessenger class. To subclassers (that is, currently, transports) the only difference is that some overloaded methods have a different name (class hierarchy reasons made it impossible to preserve the names without forcing an API change for applications). The other difference which is not API visible, is that it implements the standard MessengerState behaviour and semantics required by the changes in the endpoint framework. This the only base messenger class meant to be extended by outside code that is in the impl tree. The reason being that what it replaces was there already and that new code should not become dependant upon it.
Nested Class Summary |
---|
Nested classes/interfaces inherited from interface net.jxta.util.SimpleSelectable |
---|
SimpleSelectable.IdentityReference |
Field Summary |
---|
Fields inherited from class net.jxta.endpoint.AbstractMessenger |
---|
DEFAULT_MTU, dstAddress |
Fields inherited from class net.jxta.util.AbstractSimpleSelectable |
---|
identityReference |
Fields inherited from interface net.jxta.endpoint.Messenger |
---|
ANYSTATE, BREAKING, BROKEN, CLOSED, CLOSING, CONNECTED, DISCONNECTED, DISCONNECTING, IDLE, RECONCLOSING, RECONNECTING, RECONSATURATED, RESOLCLOSING, RESOLPENDING, RESOLSATURATED, RESOLVED, RESOLVING, SATURATED, SENDING, SENDINGSATURATED, TERMINAL, UNRESOLVABLE, UNRESOLVED, UNRESOLVING, USABLE |
Constructor Summary | |
---|---|
BlockingMessenger(PeerGroupID homeGroupID,
EndpointAddress dest,
boolean selfDestruct)
Constructor. |
Method Summary | |
---|---|
void |
close()
Close this messenger after processing any pending messages. |
protected abstract void |
closeImpl()
Close connection. |
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. |
protected EndpointAddress |
getDestAddressToUse(String service,
String serviceParam)
Assemble a destination address for a message based upon the messenger default destination address and the optional provided overrides. |
EndpointAddress |
getLogicalDestinationAddress()
Returns the logical destination of this messenger. |
protected abstract EndpointAddress |
getLogicalDestinationImpl()
Obtain the logical destination address from the implementer (a transport for example). |
int |
getState()
Returns the current state. |
boolean |
isClosed()
Returns true if this messenger is closed and no longer
accepting messages to be sent. |
protected abstract boolean |
isIdleImpl()
return true if this messenger has not been used for a long time. |
void |
resolve()
Force the messenger to start resolving if it is not resolved yet. |
void |
sendMessageB(Message msg,
String service,
String serviceParam)
Simple sending: blocks until the message was accepted for sending or the messenger is not Messenger.USABLE ; whichever occurs
first. |
protected abstract void |
sendMessageBImpl(Message message,
String service,
String param)
Send a message blocking as needed until the message is sent. |
boolean |
sendMessageN(Message msg,
String service,
String serviceParam)
Sends a message to the destination specified at construction. |
void |
setOwner(Object owner)
Sets an owner for this blocking messenger. |
protected void |
shutdown()
A transport may call this to cause an orderly closure of its messengers. |
Methods inherited from class net.jxta.endpoint.AbstractMessenger |
---|
flush, getDestinationAddress, getDestinationAddressObject, getMTU, isIdle, isSynchronous, itemChanged, sendMessage, sendMessage, sendMessage, setStateLock, toString, waitState |
Methods inherited from class net.jxta.util.AbstractSimpleSelectable |
---|
getIdentityReference, haveListeners, notifyChange, register, registerListener, unregister, unregisterListener |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface net.jxta.util.SimpleSelectable |
---|
getIdentityReference, register, unregister |
Constructor Detail |
---|
public BlockingMessenger(PeerGroupID homeGroupID, EndpointAddress dest, boolean selfDestruct)
homeGroupID
- the group that this messenger works for. This is the group of the endpoint service or transport
that created this messenger.dest
- where messages should be addressed toselfDestruct
- true if this messenger must self close destruct when idle. Warning: If selfDestruct is used,
this messenger will remained referenced for as long as isIdleImpl returns false.Method Detail |
---|
public void setOwner(Object owner)
owner
- The object that should be kept referenced at least as long as this one.protected EndpointAddress getDestAddressToUse(String service, String serviceParam)
service
- The destination service or null
to use default.serviceParam
- The destination service parameter or null
to
use default.protected final void shutdown()
public 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.
This is a minimal implementation. It may not detect closure
initiated by the other side unless the messenger was actually used
since. A more accurate (but not mandatory implementation) would
actually go and check the underlying connection, if relevant...unless
breakage initiated by the other side is actually reported asynchronously
when it happens. Breakage detection from the other side need not
be reported atomically with its occurrence. This not very important
since we canonicalize transport messengers and so do not need to
aggressively collect closed ones. When not used, messengers die by themselves.
We overload isClosed because many messengers still use super.isClosed()
as part of their own implementation or don't override it at all. They
expect it to be true only when all is shutdown; not while we're closing
gently.
FIXME - jice@jxta.org 20040413: transports should get a deeper retrofit eventually.
isClosed
in interface Messenger
isClosed
in class AbstractMessenger
true
if this messenger is closed, otherwise false
.public final 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.
getLogicalDestinationAddress() requires resolution (it's the address advertised by the other end).
For a blocking messenger it's easy. We're born resolved. So, just ask the implementor what it is.
Messenger.getDestinationAddress()
public final void close()
Messenger.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 Messenger.TERMINAL
states (which are
also Messenger.IDLE
states). Therefore, if one is interested in the
outcome of the closure, one may wait for the messenger to be in a
Messenger.TERMINAL
or Messenger.IDLE
state, and check which it is.
Messenger.CLOSED
denotes success (all outstanding messages have been
sent), as opposed to Messenger.UNRESOLVABLE
or Messenger.BROKEN
.
Some transports historically overload the close method of BlockingMessenger.
The final is there to make sure we know about it. However, there should be no
harm done if the unchanged code is renamed to closeImpl; even if it calls super.close().
The real problem, however, is transports calling close (was their own, but now it means this one), when
they want to break. It will make things look like someone just called close, but it will not
actually break anything. However, that will cause the state machine to go through the close process.
this will end up calling closeImpl(). That will do.
public void sendMessageB(Message msg, String service, String serviceParam) throws IOException
Messenger.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 Messenger.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 Messenger.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
Messenger.IDLE
state that is either Messenger.CLOSED
or a Messenger.USABLE
state, then it may be inferred
that all outstanding messages have been processed without this messenger detecting an error.Messenger.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.public final boolean sendMessageN(Message msg, String service, String serviceParam)
Messenger.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 Messenger.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
Messenger.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 Messenger.IDLE
state that is either Messenger.CLOSED
or a Messenger.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.Messenger.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 final void resolve()
public final int getState()
public final Messenger getChannelMessenger(PeerGroupID redirection, String service, String serviceParam)
Messenger.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)
protected abstract void closeImpl()
protected abstract void sendMessageBImpl(Message message, String service, String param) throws IOException
message
- The message to send.service
- The destination service.param
- The destination serivce param.
IOException
- Thrown for errors encountered while sending the message.protected abstract boolean isIdleImpl()
true
if theis messenger is, by it's own definition, idle.protected abstract EndpointAddress getLogicalDestinationImpl()
|
JXSE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |