Project JXTA

net.jxta.endpoint
Class ChannelMessenger

java.lang.Object
  extended bynet.jxta.util.AbstractSimpleSelectable
      extended bynet.jxta.endpoint.AbstractMessenger
          extended bynet.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

Nested Class Summary
 
Nested classes inherited from class net.jxta.util.SimpleSelectable
SimpleSelectable.IdentityReference
 
Field Summary
static String InsertedServicePrefix
          insertedServicePrefix This is how all valid inserted services start.
protected  String origService
           
protected  String origServiceParam
           
 
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
ChannelMessenger(EndpointAddress baseAddress, PeerGroupID groupRedirection, String origService, String origServiceParam)
          Create a new ChannelMessenger
 
Method Summary
protected  String effectiveParam(String service, String serviceParam)
          Figure out what the param string will be after mangling (if required) and applying relevant defaults.
protected  String effectiveService(String service)
          Figure out what the service string will be after mangling (if required) and applying relevant defaults.
 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.

 void sendMessage(Message msg, String service, String serviceParam, OutgoingMessageEventListener listener)
          Deprecated. Implements deprecated method.
 void setMessageWatcher(ListenerAdaptor messageWatcher)
          Deprecated. This method is in support of deprecated methods.
 
Methods inherited from class net.jxta.endpoint.AbstractMessenger
flush, getDestinationAddress, getDestinationAddressObject, getMTU, isClosed, isIdle, isSynchronous, itemChanged, sendMessage, sendMessage, setStateLock, 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, 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
 
Methods inherited from interface net.jxta.util.SimpleSelectable
getIdentityReference, itemChanged, register, unregister
 

Field Detail

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
Constructor Detail

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.
Method Detail

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:

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

JXTA J2SE