Project 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 rather than using this API directly.


Field Summary
static int HighPrecedence
           
static int LowPrecedence
           
static int MediumPrecedence
           
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, 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 transpt)
          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)
          Delivers the provided message to the correct listener as specified by the message's destination address.
 Iterator 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.
 PeerGroup getGroup()
          Returns the group to which this EndpointService is attached.
 MessageTransport getMessageTransport(String name)
          Get a MessageTransport by name
 Messenger getMessenger(EndpointAddress addr)
          Deprecated. This convenience method adds little value. It is strictly equivalent to getMessenger(addr, null)
 Messenger getMessenger(EndpointAddress addr, Object hint)
          Behaves like getMessengerImmediate(EndpointAddress, Object), except that the invoker is blocked until the messenger resolves or fails to do so.
 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. It now always return true. Try and get a messenger instead.
 void propagate(Message srcMsg, String serviceName, String serviceParam)
          Propagates the given message through all the endpoint protocols that are available to this endpoint.
 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

public static final int LowPrecedence
See Also:
Constant Field Values

MediumPrecedence

public static final int MediumPrecedence
See Also:
Constant Field Values

HighPrecedence

public static final int HighPrecedence
See Also:
Constant Field Values
Method Detail

getGroup

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

Returns:
PeerGroup the group.

getMessengerImmediate

public Messenger getMessengerImmediate(EndpointAddress addr,
                                       Object hint)
Returns a messenger to the specified destination. The canonical messenger is shared between all channels which destination contains 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 succesfully create a messenger to the given destination. There is no garantee 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 hint to be supplied to whichever transport ends-up making the the real messenger. May be null, when no hint applies.
Returns:
The messenger, not necessarily functional, nor resolved. May be null if the address is not handled by any of the available transports.
See Also:
EndpointAddress, ChannelMessenger

getMessenger

public Messenger getMessenger(EndpointAddress addr,
                              Object hint)
Behaves like getMessengerImmediate(EndpointAddress, Object), except that the invoker is blocked until the messenger resolves or fails to do so.

Parameters:
addr - the destination address.
hint - A hint if there is one. Null, otherwise.
Returns:
The messenger. null is returned if the destination address is not reachable.

getCanonicalMessenger

public 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 no local transport handles this type address.
See Also:
Messenger

removeMessengerEventListener

public 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

public 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 highest precedence Listeners are called in decreasing order of precedence. Listeners with equal precedence are called in unpredictible order relative to each other. 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

public void propagate(Message srcMsg,
                      String serviceName,
                      String serviceParam)
               throws IOException
Propagates the given message through all the endpoint protocols that are available to this endpoint. Some or all of these endpoint protocols may silently drop the message. Each endpoint protocol may interpret the resquest for propagation differenly. The endpointService does not define which destinations the message will actually reach.

The concatenation of the serviceName and serviceParam arguments uniquely designates the listener to which the message must be delivered on arrival.

WARNING: The message object should not be reused or modified after the call is made. Concurrent modifications will produce unexpected results.

Parameters:
srcMsg - the message to be propagated.
serviceName - a destination service name
serviceParam - a destination queue name within that service
Throws:
IOException - if the message could not be propagated

ping

public boolean ping(EndpointAddress addr)
Deprecated. It now always return true. Try and get a messenger instead.

Verifies that the given address can be reached. The verification is performed by the endpoint protocol designated by the given address, as returned by the getProtocolName() method of this address.

The method, and accuracy of the verification depends upon each endpoint protocol.

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

addIncomingMessageListener

public 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.
  3. *

Parameters:
listener - the listener
serviceName - The name of the service destination which will be matched against destination endpoint addresses.
serviceParam - String containting the value of the service parameter which will be matched against destination endpoint addresses. May be null.
Returns:
true if the listener was registered, otherwise false.

removeIncomingMessageListener

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

Parameters:
serviceName - The name of the service destination which will be matched against destination endpoint addresses.
serviceParam - String containting the value of the service parameter which will be matched against destination endpoint addresses. May be null.
Returns:
The listener which was removed.

addIncomingMessageFilterListener

public 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

public 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 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.

removeIncomingMessageFilterListener

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

Parameters:
listener - the listener that was registered

removeOutgoingMessageFilterListener

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

Parameters:
listener - the listener that was registered

demux

public void demux(Message msg)
Delivers the provided message to the correct listener as specified by the message's destination address.

Parameters:
msg - The message to be delivered.

addMessageTransport

public MessengerEventListener addMessageTransport(MessageTransport transpt)
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 optionaly 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:
transpt - the MessageTransport to be installed.
Returns:
A messenger event listener to invoke when incoming messengers are created. Null if the MessageTransport was not installed.

removeMessageTransport

public 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:
boolean true if the transport was removed, otherwise false.

getAllMessageTransports

public Iterator getAllMessageTransports()
Get an iterator of the MessageTransports available to this EndpointService.

Returns:
the iterator of all message transports.

getMessageTransport

public MessageTransport getMessageTransport(String name)
Get a MessageTransport by name

Parameters:
name - The name of the MessageTransport
Returns:
MessageTransport associated with that name

getMessenger

public Messenger getMessenger(EndpointAddress addr)
Deprecated. This convenience method adds little value. It is strictly equivalent to getMessenger(addr, null)

Builds and returns an Messager that may be used to send messages via this endpoint to the specified destination.

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

getMessenger

public 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:
boolean true if the messenger is queued for construction otherwise false.

JXTA J2SE