JXTA

net.jxta.endpoint
Interface EndpointService

All Superinterfaces:
EndpointListener, Module, Service

public interface EndpointService
extends Service, EndpointListener

The EndpointService provides the API for sending and receiving messages between peers. In general, applications and services use the PipeService, or JxtaSocket rather than using this API directly.


Field Summary
static int HighPrecedence
          High Priority Messenger Event Listener.
static int LowPrecedence
          Low Priority Messenger Event Listener.
static int MediumPrecedence
          Medium Priority Messenger Event Listener.
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_DISABLED, START_OK
 
Method Summary
 void addIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
          Registers a message filter listener.
 boolean addIncomingMessageListener(EndpointListener listener, String serviceName, String serviceParam)
          Add a listener for the specified address.
 MessengerEventListener addMessageTransport(MessageTransport transport)
          Adds the specified MessageTransport to this endpoint.
 boolean addMessengerEventListener(MessengerEventListener listener, int priority)
          Adds the specified listener for all messenger creation.
 void addOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
          Registers a message filter listener.
 void demux(Message msg)
          Deprecated. Please convert your code to use the EndpointListener.processIncomingMessage(Message,EndpointAddress,EndpointAddress) method instead. The addressing method used by demux() was never part of the formal JXTA protocol specification but was a defacto part because demux() depended upon it.
 Iterator<MessageTransport> getAllMessageTransports()
          Get an iterator of the MessageTransports available to this EndpointService.
 Messenger getCanonicalMessenger(EndpointAddress addr, Object hint)
          Creates and maps a canonical messenger to the specified destination.
 Messenger getDirectMessenger(EndpointAddress addr, Object hint, boolean exclusive)
          Returns a Direct Messenger that may be used to send messages via this endpoint to the specified destination.
 PeerGroup getGroup()
          Returns the group to which this EndpointService is attached.
 EndpointListener getIncomingMessageListener(String serviceName, String serviceParam)
          Get the listener for the specified address.
 MessageTransport getMessageTransport(String name)
          Get a Message Transport by protocol name.
 Messenger getMessenger(EndpointAddress addr)
          Returns a Messenger that may be used to send messages via this endpoint to the specified destination.
 Messenger getMessenger(EndpointAddress addr, Object hint)
          Returns a messenger for the specified destination address.
 boolean getMessenger(MessengerEventListener listener, EndpointAddress addr, Object hint)
          Deprecated. This method is being phased out. Prefer one of the other non-blocking variants. If a listener style paradigm is required, use ListenerAdaptor which emulates this functionality.
 Messenger getMessengerImmediate(EndpointAddress addr, Object hint)
          Returns a messenger to the specified destination.
 boolean ping(EndpointAddress addr)
          Deprecated. The cost of performing this operation is generally the same as getting a Messenger for the destination. Using getMessenger() is a better approach because the resulting Messenger is generally needed soon after ping.
 void propagate(Message message, String serviceName, String serviceParam)
          Propagates (broadcasts) a message via all available Message Transports.
 void propagate(Message message, String serviceName, String serviceParam, int initialTTL)
          Propagates (broadcasts) a message via all available Message Transports.
 MessageFilterListener removeIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
          Removes the given listener previously registered under the given element name
 EndpointListener removeIncomingMessageListener(String serviceName, String serviceParam)
          Remove the listener for the specified address.
 boolean removeMessageTransport(MessageTransport transpt)
          Removes the given MessageTransport protocol from this endpoint service.
 boolean removeMessengerEventListener(MessengerEventListener listener, int priority)
          Removes the specified listener.
 MessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
          Removes the given listener previously registered under the given element name.
 
Methods inherited from interface net.jxta.service.Service
getImplAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Module
init, startApp, stopApp
 
Methods inherited from interface net.jxta.endpoint.EndpointListener
processIncomingMessage
 

Field Detail

LowPrecedence

static final int LowPrecedence
Low Priority Messenger Event Listener.

See Also:
Constant Field Values

MediumPrecedence

static final int MediumPrecedence
Medium Priority Messenger Event Listener.

See Also:
Constant Field Values

HighPrecedence

static final int HighPrecedence
High Priority Messenger Event Listener.

See Also:
Constant Field Values
Method Detail

getGroup

PeerGroup getGroup()
Returns the group to which this EndpointService is attached.

Returns:
the group.

getMessengerImmediate

Messenger getMessengerImmediate(EndpointAddress addr,
                                Object hint)
Returns a messenger to the specified destination.

The canonical messenger is shared between all channels who's destination contain the same protocol name and protocol address, in all groups that have access to the same transport. The ChannelMessenger returned is configured to send messages to the specified service name and service param when these are not specified at the time of sending.

The channel will also ensure delivery to this EndpointService's group on arrival. The channel is not shared with any other module. That is, each endpoint service interface object (as returned by PeerGroup.getEndpointService()) will return a different channel messenger for the same destination. However, there is no guarantee that two invocations of the same endpoint service interface object for the same destination will return different channel objects. Notably, if the result of a previous invocation is still strongly referenced and in a Messenger.USABLE state, then that is what this method will return.

This method returns immediately. The messenger is not necessarily resolved (the required underlying connection established, for example), and it might never resolve at all. Changes in the state of a messenger may monitored with Messenger.getState() and Messenger.waitState(int, long). One may monitor multiple messengers (and Messages) at a time by using a SimpleSelector. One may also arrange to have a listener invoked when resolution is complete by using ListenerAdaptor.

The hint is interpreted by the transport. The only transport known to consider hints is the endpoint router, and the hint is a route. As a result, if addr is in the form: jxta://uniqueID, then hint may be a RouteAdvertisement. If that route is valid the router will add it to it's cache of route and may then use it to successfully create a messenger to the given destination. There is no guarantee at this time that the route will end up being the one specified, nor that this route will be used only for this messenger (likely the opposite), nor that it will remain in use in the future, nor that it will be used at all. However, if there is no other route, and if the specified route is valid, it will be used rather than seeking an alternative.

Parameters:
addr - The complete destination address.
hint - A optional hint to be supplied to whichever transport ends-up making the real messenger. May be null, when no hint applies.
Returns:
A messenger for the specified destination address or null if the address is not handled by any of the available Message Transports. The messenger, if returned, is not necessarily functional, nor resolved.
See Also:
ChannelMessenger

getMessenger

Messenger getMessenger(EndpointAddress addr,
                       Object hint)
Returns a messenger for the specified destination address.

Behaves like getMessengerImmediate(EndpointAddress,Object), except that the invoker is blocked until the Messenger either resolves or it is determined that no usable messenger can be created.

Parameters:
addr - The destination address.
hint - A optional hint to be supplied to whichever transport ends-up making the real messenger. May be null, when no hint applies.
Returns:
A messenger for the specified destination address or null if the destination address is not reachable.

getCanonicalMessenger

Messenger getCanonicalMessenger(EndpointAddress addr,
                                Object hint)
Creates and maps a canonical messenger to the specified destination.

Behaves like getMessengerImmediate(EndpointAddress,Object) except that it returns a canonical messenger.

The messenger is said to be canonical, because there is only one such live object for any given destination address. The term "live", here means that the messenger is not in any of the Messenger.TERMINAL states as defined by MessengerState. Therefore, for a given destination there may be any number of messengers in a Messenger.TERMINAL state, but at most one in any other state. As long as such an object exists, all calls to getCanonicalMessenger() for the same address return this very object.

When first created, a canonical messenger is usually in the Messenger.UNRESOLVED state. It becomes resolved by obtaining an actual transport messenger to the destination upon the first attempt at using it or when first forced to attempt resolution. Should resolution fail at that point, it becomes Messenger.UNRESOLVABLE. Otherwise, subsequent, failures are repaired automatically by obtaining a new transport messenger when needed. If a failure cannot be repaired, the messenger becomes Messenger.BROKEN.

getCanonicalMessenger() is a recursive function. Exploration of the parent endpoint is done automatically.

Note 1: This method is the most fundamental messenger instantiation method. It creates a different messenger for each variant of destination address passed to the constructor. In general invokers should use plain addresses; stripped of any service-specific destination.

Note 2: The messengers that this method returns, are not generally meant to be used directly. They provide a single queue for all invokers, and do not perform group redirection and only support only a subset of the sendMessage() methods. One must get a properly configured channel in order to send messages.

If one of the other getMessenger() methods fits the application needs, it should be preferred.

Parameters:
addr - The destination address. It is recommended, though not mandatory, that the address be stripped of its service name and service param elements.
hint - An object, of a type specific to the protocol of the address, that may be provide additional information to the transport in establishing the connection. Typically but not necessarily, this is a route advertisement. If the transport cannot use the hint, or if it is null, it will be ignored.
Returns:
A Canonical messenger that obtains transport messengers to the specified address, from LOCAL transports. Returns null if no local transport handles this type address.

removeMessengerEventListener

boolean removeMessengerEventListener(MessengerEventListener listener,
                                     int priority)
Removes the specified listener.

Parameters:
listener - The listener that would have been called.
priority - Priority set from which to remove this listener.
Returns:
true if the listener was removed, otherwise false.

addMessengerEventListener

boolean addMessengerEventListener(MessengerEventListener listener,
                                  int priority)
Adds the specified listener for all messenger creation.

Parameters:
listener - The listener that will be called.
priority - Order of precedence requested (from 0 to 2). 2 has the highest precedence. Listeners are called in decreasing order of precedence. Listeners with equal precedence are called in an unspecified order. There cannot be more than one listener object for a given precedence. Redundant calls have no effect.
Returns:
true if the listener was added, otherwise false.

propagate

void propagate(Message message,
               String serviceName,
               String serviceParam)
               throws IOException
Propagates (broadcasts) a message via all available Message Transports. Each Message Transport that implements propagation will send the message using it's broadcast functionality to a configured broadcast address. Any peers in the same network scope listening on that broadcast address will receive the propagated message.

The message will be sent using the default TTL value (which is unspecified).

Parameters:
message - The message to be propagated. The message will not be modified by this method.
serviceName - The name of the destination service.
serviceParam - An optional parameter for the destination service or null.
Throws:
IOException - Thrown if the message could not be propagated.

propagate

void propagate(Message message,
               String serviceName,
               String serviceParam,
               int initialTTL)
Propagates (broadcasts) a message via all available Message Transports. Each Message Transport that implements propagation will send the message using it's broadcast functionality to a configured broadcast address. Any peers in the same network scope listening on that broadcast address will receive the propagated message.

Parameters:
message - The message to be propagated. The message will not be modified by this method.
serviceName - The name of the destination service.
serviceParam - An optional parameter for the destination service or null.
initialTTL - The requested initial TTL for this message. The actual TTL value used may be lower than this value but will never be higher.

ping

@Deprecated
boolean ping(EndpointAddress addr)
Deprecated. The cost of performing this operation is generally the same as getting a Messenger for the destination. Using getMessenger() is a better approach because the resulting Messenger is generally needed soon after ping.

Verifies that the given address can be reached. The method, and accuracy of the verification depends upon each Message Transport. In some cases the address may be contacted to determine connectivity but this is not guaranteed.

Parameters:
addr - is the Endpoint Address to ping.
Returns:
true if the address can be reached otherwise false.

addIncomingMessageListener

boolean addIncomingMessageListener(EndpointListener listener,
                                   String serviceName,
                                   String serviceParam)
Add a listener for the specified address.

A single registered listener will be called for incoming messages when (in order of preference) :

  1. The service name and service parameter match exactly to the service name and service parameter specified in the destination address of the message.
  2. The service name matches exactly the service name from the message destination address and service parameter is null.

Parameters:
listener - The listener which will be called when messages are received for the registered destination.
serviceName - The name of the service destination which will be matched against incoming message destination endpoint addresses.
serviceParam - An optional service parameter value which will be matched against destination endpoint addresses. May be null.
Returns:
true if the listener was registered, otherwise false.

getIncomingMessageListener

EndpointListener getIncomingMessageListener(String serviceName,
                                            String serviceParam)
Get the listener for the specified address.

Parameters:
serviceName - The service name to which the listener is registered.
serviceParam - The service parameter to which the listener is registered. May be null.
Returns:
The currently registered listener or null if there is no listener for the specified name and parameter.

removeIncomingMessageListener

EndpointListener removeIncomingMessageListener(String serviceName,
                                               String serviceParam)
Remove the listener for the specified address.

Parameters:
serviceName - The service name to which the listener is registered.
serviceParam - The service parameter to which the listener is registered. May be null.
Returns:
The listener which was removed or null if there was no listener for the specified name and parameter.

addIncomingMessageFilterListener

void addIncomingMessageFilterListener(MessageFilterListener listener,
                                      String namespace,
                                      String name)
Registers a message filter listener. Each message will be tested against the list of filters as part of its sending or receiving.

The listener is invoked for a message when:

Parameters:
listener - The filter which will be called.
namespace - Only messages containing elements of this namespace which also match the 'name' parameter will be processed. null may be use to specify all namespaces.
name - only messages containing elements of this name which also match the 'namespace' parameter will be processed. null may be use to specify all names.

addOutgoingMessageFilterListener

void addOutgoingMessageFilterListener(MessageFilterListener listener,
                                      String namespace,
                                      String name)
Registers a message filter listener. Each message will be tested against the list of filters as part of its sending or receiving.

The listener is invoked for a message when:

Parameters:
listener - The filter which will be called.
namespace - Only messages containing elements of this namespace which also match the 'name' parameter will be processed. null may be used to specify all namespaces.
name - only messages containing elements of this name which also match the 'namespace' parameter will be processed. null may be use to specify all names.

removeIncomingMessageFilterListener

MessageFilterListener removeIncomingMessageFilterListener(MessageFilterListener listener,
                                                          String namespace,
                                                          String name)
Removes the given listener previously registered under the given element name

Parameters:
listener - the listener to remove
namespace - the name space
name - the name
Returns:
the removed listener

removeOutgoingMessageFilterListener

MessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener,
                                                          String namespace,
                                                          String name)
Removes the given listener previously registered under the given element name.

Parameters:
listener - the listener to remove
namespace - the name space
name - the name
Returns:
the removed listener

demux

@Deprecated
void demux(Message msg)
Deprecated. Please convert your code to use the EndpointListener.processIncomingMessage(Message,EndpointAddress,EndpointAddress) method instead. The addressing method used by demux() was never part of the formal JXTA protocol specification but was a defacto part because demux() depended upon it.

Delivers the provided message to the correct listener as specified by the message's destination address.

Two additional common message elements are optionally used by Message Transports in conjunction with the Endpoint Service. Message Transports may typically provide received messages to the Endpoint Service containing these elements and the Endpoint service will dispatch the messages based upon their content. Message Transports may use alternate mechanisms for determining message source and destination addresses and need not use these elements.

The jxta:EndpointSourceAddress Message Element contains an Endpoint Address for the source of this message. The source address has a variety of meanings based upon the usage of the underlying Message Transport. For low level transports such as TCP or HTTP the source address is the return address of the peer from which the message was received, ie. the hop address. For higher level Message Transports such as the Endpoint Router Transport or the TLS transport the source address is the virtual Endpoint Address of the peer which originated the message regardless of any intervening hops the message may have made.

The jxta:EndpointDestinationAddress Message Element contains an Endpoint Address which will be used by the Endpoint Service to dispatch a received message to the recipient specified by the service name and service parameter. The protocol address is also provided to the recipient service and can be used in some protocols for determining how the message was received. For example a service may wish to handle messages which were sent directly differently than messages which were sent via propagation.

Parameters:
msg - The message to be delivered.

addMessageTransport

MessengerEventListener addMessageTransport(MessageTransport transport)
Adds the specified MessageTransport to this endpoint. A MessageTransport may only be added if there are no other equivalent MessageTransports available (as determined by equals()).

The MessageTransport becomes usable by the endpoint service to send unicast messages and optionally propagation and ping messages if it is a MessageSender. The endpoint service becomes usable by this MessageTransport to handle incoming messages if it is a MessageReceiver.

Parameters:
transport - the MessageTransport to be installed.
Returns:
A messenger event listener to invoke when incoming messengers are created or null if the MessageTransport was not installed.

removeMessageTransport

boolean removeMessageTransport(MessageTransport transpt)
Removes the given MessageTransport protocol from this endpoint service.

Transports remove themselves from the list when stopped. This method is normally only called from the stoppApp method of the transport. To cleanly remove a transport, call the transport's stopApp()and allow it to call this method.

Parameters:
transpt - the MessageTransport to be removed.
Returns:
true if the Message Transport was removed, otherwise false.

getAllMessageTransports

Iterator<MessageTransport> getAllMessageTransports()
Get an iterator of the MessageTransports available to this EndpointService.

Returns:
the iterator of all message transports.

getMessageTransport

MessageTransport getMessageTransport(String name)
Get a Message Transport by protocol name.

Parameters:
name - The protocol name of the MessageTransport.
Returns:
The Message Transport for the specified protocol name or null if there is no matching Message Transport

getMessenger

Messenger getMessenger(EndpointAddress addr)
Returns a Messenger that may be used to send messages via this endpoint to the specified destination.

Parameters:
addr - the destination address.
Returns:
The messenger or null is returned if the destination address is not reachable.

getMessenger

@Deprecated
boolean getMessenger(MessengerEventListener listener,
                                EndpointAddress addr,
                                Object hint)
Deprecated. This method is being phased out. Prefer one of the other non-blocking variants. If a listener style paradigm is required, use ListenerAdaptor which emulates this functionality.

Asynchronously acquire a messenger for the specified address. The listener will be called when the messenger has been constructed.

Parameters:
listener - the listener to call when the messenger is ready.
addr - the destination for the messenger.
hint - the messenger hint, if any, otherwise null.
Returns:
true if the messenger is queued for construction otherwise false.

getDirectMessenger

Messenger getDirectMessenger(EndpointAddress addr,
                             Object hint,
                             boolean exclusive)
Returns a Direct Messenger that may be used to send messages via this endpoint to the specified destination.

Direct messengers are non self destructive, they must be explicilty closed.

Parameters:
addr - the destination address.
hint - the messenger hint, if any, otherwise null.
exclusive - if true avoids caching the messenger
Returns:
The messenger or null is returned if the destination address is not reachable.
Throws:
IllegalArgumentException - if hint is not of RouteAdvertisement, or PeerAdvertisement type.

JXSE