JXTA

net.jxta.impl.endpoint
Class EndpointServiceInterface

java.lang.Object
  extended by net.jxta.impl.endpoint.EndpointServiceInterface
All Implemented Interfaces:
EndpointListener, EndpointService, Module, Service

 class EndpointServiceInterface
extends Object
implements EndpointService

Provides an interface object appropriate for applications using the endpoint service. The interface provides a number of convenience features and implementation necessary for legacy features.


Field Summary
 
Fields inherited from interface net.jxta.endpoint.EndpointService
HighPrecedence, LowPrecedence, MediumPrecedence
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_DISABLED, START_OK
 
Constructor Summary
EndpointServiceInterface(EndpointServiceImpl endpointService)
          Builds a new interface object.
 
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 prio)
          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.
protected  void finalize()
          

This is rather heavy-weight if instances are frequently created and discarded since finalization significantly delays GC.

 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.
 ModuleImplAdvertisement getImplAdvertisement()
          Returns the advertisement for this service.
 EndpointListener getIncomingMessageListener(String serviceName, String serviceParam)
          Get the listener for the specified address.
 EndpointService getInterface()
          Service objects are not manipulated directly to protect usage of the service.
 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. legacy support
 Messenger getMessengerImmediate(EndpointAddress addr, Object hint)
          Returns a messenger to the specified destination.
 void init(PeerGroup peerGroup, ID id, Advertisement implAdv)
          Initialize the module, passing it its peer group and advertisement.
 boolean ping(EndpointAddress addr)
          Deprecated. 
 void processIncomingMessage(Message message, EndpointAddress source, EndpointAddress destination)
          This method is invoked by the EndpointService for each incoming message which is addressed to this listener.
 void propagate(Message msg, String serviceName, String serviceParam)
          Propagates (broadcasts) a message via all available Message Transports.
 void propagate(Message msg, 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 prio)
          Removes the specified listener.
 MessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
          Removes the given listener previously registered under the given element name.
 int startApp(String[] arg)
          Complete any remaining initialization of the module.
 void stopApp()
          Stop a module.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EndpointServiceInterface

public EndpointServiceInterface(EndpointServiceImpl endpointService)
Builds a new interface object.

Parameters:
endpointService - the endpoint service that we will front.
Method Detail

finalize

protected void finalize()
                 throws Throwable

This is rather heavy-weight if instances are frequently created and discarded since finalization significantly delays GC.

Overrides:
finalize in class Object
Throws:
Throwable

init

public void init(PeerGroup peerGroup,
                 ID id,
                 Advertisement implAdv)
Initialize the module, passing it its peer group and advertisement.

Note: when subclassing one of the existing PeerGroup implementations (which implement Module), it may not be recommended to overload the init method. See the documentation of the PeerGroup class being subclassed.

it is there only to satisfy the requirements of the interface that we implement. Ultimately, the API should define two levels of interfaces : one for the real service implementation and one for the interface object. Right now it feels a bit heavy to so that since the only different between the two would be init() and may-be getName().

Specified by:
init in interface Module
Parameters:
peerGroup - The PeerGroup from which this Module can obtain services. If this module is a Service, this is also the PeerGroup of which this module is a service.
id - Identity of Module within group. modules can use it as a the root of their namespace to create names that are unique within the group but predictable by the same module on another peer. This is normally the ModuleClassID which is also the name under which the module is known by other modules. For a group it is the PeerGroupID itself. The parameters of a service, in the Peer configuration, are indexed by the assignedID of that service, and a Service must publish its run-time parameters in the Peer Advertisement under its assigned ID.
implAdv - The implementation advertisement for this Module. It is permissible to pass null if no implementation advertisement is available. This may happen if the implementation was selected by explicit class name rather than by following an implementation advertisement. Modules are not required to support that style of loading, but if they do, then their documentation should mention it.

startApp

public int startApp(String[] arg)
Complete any remaining initialization of the module. The module should be fully functional after startApp() is completed. That is also the opportunity to supply arbitrary arguments (mostly to applications).

If this module is a PeerGroup service, it may be invoked several times depending on its return value.

This is here for temporary class hierarchy reasons. it is ALWAYS ignored. By definition, the interface object protects the real object's start/stop methods from being called

Specified by:
startApp in interface Module
Parameters:
arg - An array of Strings forming the parameters for this Module.
Returns:
int A status indication which may be one of Module.START_OK, Module.START_AGAIN_PROGRESS, Module.START_AGAIN_STALLED, which indicates partial or complete success, or any other value (negative values are recommended for future compatibility), which indicates failure.

stopApp

public void stopApp()
Stop a module. This may be called any time after init() completes and should not assume that startApp() has been called or completed.

The Module cannot be forced to comply, but in the future we might be able to deny it access to anything after some timeout.

This is here for temporary class hierarchy reasons. it is ALWAYS ignored. By definition, the interface object protects the real object's start/stop methods from being called

This request is currently ignored.

Specified by:
stopApp in interface Module

getImplAdvertisement

public ModuleImplAdvertisement getImplAdvertisement()
Returns the advertisement for this service.

Specified by:
getImplAdvertisement in interface Service
Returns:
Advertisement the advertisement. This is always a ModuleImplAdvertisement.

getInterface

public EndpointService getInterface()
Service objects are not manipulated directly to protect usage of the service. A Service interface is returned to access the service methods.

Sort of absurd but this is part of the API we're implementing. We would not do a two-level API just for that.

Specified by:
getInterface in interface Service
Returns:
Service public interface of the service

getGroup

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

Specified by:
getGroup in interface EndpointService
Returns:
the group.

getCanonicalMessenger

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

Behaves like EndpointService.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.

Specified by:
getCanonicalMessenger in interface EndpointService
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.

getMessengerImmediate

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

Specified by:
getMessengerImmediate in interface EndpointService
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

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

Specified by:
getMessenger in interface EndpointService
Parameters:
addr - the destination address.
Returns:
The messenger or null is returned if the destination address is not reachable.

getMessenger

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

Behaves like EndpointService.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.

Specified by:
getMessenger in interface EndpointService
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.

propagate

public void propagate(Message msg,
                      String serviceName,
                      String serviceParam)
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).

Specified by:
propagate in interface EndpointService
Parameters:
msg - 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.

propagate

public void propagate(Message msg,
                      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.

Specified by:
propagate in interface EndpointService
Parameters:
msg - 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.

demux

public void demux(Message msg)
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.

Specified by:
demux in interface EndpointService
Parameters:
msg - The message to be delivered.

processIncomingMessage

public void processIncomingMessage(Message message,
                                   EndpointAddress source,
                                   EndpointAddress destination)
This method is invoked by the EndpointService for each incoming message which is addressed to this listener.

Specified by:
processIncomingMessage in interface EndpointListener
Parameters:
message - Incoming message
source - Endpoint Address of the source of the message.
destination - Endpoint Address of the destination of the message.

ping

@Deprecated
public boolean ping(EndpointAddress addr)
Deprecated. 

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.

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

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

Specified by:
addMessageTransport in interface EndpointService
Parameters:
transpt - 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

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.

Specified by:
removeMessageTransport in interface EndpointService
Parameters:
transpt - the MessageTransport to be removed.
Returns:
true if the Message Transport was removed, otherwise false.

getAllMessageTransports

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

Specified by:
getAllMessageTransports in interface EndpointService
Returns:
the iterator of all message transports.

getMessageTransport

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

Specified by:
getMessageTransport in interface EndpointService
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

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.

Specified by:
addIncomingMessageListener in interface EndpointService
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

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

Specified by:
getIncomingMessageListener in interface EndpointService
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.

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:

Specified by:
addIncomingMessageFilterListener in interface EndpointService
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:

Specified by:
addOutgoingMessageFilterListener in interface EndpointService
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

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

Specified by:
removeIncomingMessageFilterListener in interface EndpointService
Parameters:
listener - the listener to remove
namespace - the name space
name - the name
Returns:
the removed listener

removeOutgoingMessageFilterListener

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

Specified by:
removeOutgoingMessageFilterListener in interface EndpointService
Parameters:
listener - the listener to remove
namespace - the name space
name - the name
Returns:
the removed listener

removeIncomingMessageListener

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

Specified by:
removeIncomingMessageListener in interface EndpointService
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.

addMessengerEventListener

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

Specified by:
addMessengerEventListener in interface EndpointService
Parameters:
listener - The listener that will be called.
prio - 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.

removeMessengerEventListener

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

Specified by:
removeMessengerEventListener in interface EndpointService
Parameters:
listener - The listener that would have been called.
prio - Priority set from which to remove this listener.
Returns:
true if the listener was removed, otherwise false.

getMessenger

@Deprecated
public boolean getMessenger(MessengerEventListener listener,
                                       EndpointAddress addr,
                                       Object hint)
Deprecated. legacy support

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

Specified by:
getMessenger in interface EndpointService
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

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

Specified by:
getDirectMessenger in interface EndpointService
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.

JXSE