net.jxta.endpoint
Class ChannelMessenger
java.lang.Object
net.jxta.util.AbstractSimpleSelectable
net.jxta.endpoint.AbstractMessenger
net.jxta.endpoint.ChannelMessenger
- All Implemented Interfaces:
- Messenger, SimpleSelectable
- Direct Known Subclasses:
- AsyncChannelMessenger
public abstract class ChannelMessenger
- extends AbstractMessenger
- implements Messenger
A Channel Messenger provides an exclusive interface to the shared messenger.
What is typically exclusive is the message queue, addressing parameters that are not usefully shared (serviceName,
serviceParam), and if needed cross-group address rewritting parameters.
This class is provided as a base for implementing such channel messengers, which are typically what
Messenger.getChannelMessenger() needs to return.
- See Also:
EndpointService
,
EndpointAddress
,
Message
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 |
Methods inherited from class net.jxta.endpoint.AbstractMessenger |
flush, getDestinationAddress, getDestinationAddressObject, getMTU, isClosed, isIdle, isSynchronous, itemChanged, sendMessage, sendMessage, setStateLock, waitState |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface net.jxta.endpoint.Messenger |
close, flush, getDestinationAddress, getDestinationAddressObject, getLogicalDestinationAddress, getMTU, getState, isClosed, isIdle, isSynchronous, resolve, sendMessage, sendMessage, sendMessageB, sendMessageN, waitState |
InsertedServicePrefix
public static final String InsertedServicePrefix
- insertedServicePrefix This is how all valid inserted services start. This lets us recognize if a message already has an
inserted service. Then we must not add another one. Only the top-most one counts. Since insertion is only done here, the
constant is defined here. Even if historically it was done within the endpoint implementation, it has become a protocol now.
- See Also:
- Constant Field Values
origService
protected String origService
origServiceParam
protected String origServiceParam
ChannelMessenger
public ChannelMessenger(EndpointAddress baseAddress,
PeerGroupID groupRedirection,
String origService,
String origServiceParam)
- Create a new ChannelMessenger
- Parameters:
baseAddress
- The network address messages go to; regardless of service, param, or group.groupRedirection
- Group to which the messages must be redirected. This is used to implement the automatic group
seggregation which has become a de-facto standard. If not null, the unique portion of the specified groupID is
prepended with InsertedServicePrefix
and inserted in every message's destination address in place of the
the original service name, which gets shifted into the begining of the service parameter. The opposite is done
on arrival to restore the original destination address before the message is delivered to the listener in the
the specified group. Messages that already bear a group redirection are not affected.origService
- The default destination service for messages sent without specifying a different service.origServiceParam
- The default destination service parameter for messages sent without specifying a different service
parameter.
effectiveService
protected String effectiveService(String service)
- Figure out what the service string will be after mangling (if required) and applying relevant defaults.
- Parameters:
service
- The service name in the unmangled address.
- Returns:
- String The service name in the mangled address.
effectiveParam
protected String effectiveParam(String service,
String serviceParam)
- Figure out what the param string will be after mangling (if required) and applying relevant defaults.
- Parameters:
service
- The service name in the unmangled address.serviceParam
- The service parameter in the unmangled address.
- Returns:
- String The service parameter in the mangled address.
setMessageWatcher
public void setMessageWatcher(ListenerAdaptor messageWatcher)
- Deprecated. This method is in support of deprecated methods.
- Give this channel the watcher that it must use whenever sendMessage(...,listener) is used. If not set,
sendMessage(..., listener) will throw.
getChannelMessenger
public 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
Messenger.sendMessage(Message, String, String,
OutgoingMessageEventListener)
legacy method. If use of this method is desired, setMessageWatcher(net.jxta.endpoint.ListenerAdaptor)
must be used first.
By default a channel refuses to make a channel.
- Specified by:
getChannelMessenger
in interface Messenger
- 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)
sendMessage
public void sendMessage(Message msg,
String service,
String serviceParam,
OutgoingMessageEventListener listener)
- Deprecated. Implements deprecated method.
- 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:
- If a listener was provided, it will always be invoked. Depending upon the outcome either the
OutgoingMessageEventListener.messageSendFailed(OutgoingMessageEvent)
or the OutgoingMessageEventListener.messageSendSucceeded(OutgoingMessageEvent)
method will be invoked:
- If the message could not be accepted for sending due to temporary resource saturation,
messageSendFailed
will be invoked. The Throwable
object returned by the OutgoingMessageEvent.getFailure()
method of the passed event object will be null.
- If the message could not be accepted for sending due to the messenger not being
Messenger.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.
- If the message is accepted for sending but later fails, then
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.
- If the message is accepted for sending and later succeeds, then
messageSendSucceeded
will be
invoked.
- If a listener was provided, it is always possible that it is invoked before this method returns.
- If no listener was provided, There will be no notification of any errors nor success 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 outsdanding messages have been processed without this messenger detecting an error.
- This method does not throw exceptions. As a result, when used with a
null
listener, it provides very
little feedback to the invoker. A messenger should be abandonned once it is in one of the Messenger.TERMINAL
states.
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.
- Specified by:
sendMessage
in interface Messenger
- Overrides:
sendMessage
in class AbstractMessenger
- 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.