|
JXTA | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.jxta.impl.endpoint.EndpointServiceInterface
class EndpointServiceInterface
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 |
---|
public EndpointServiceInterface(EndpointServiceImpl endpointService)
endpointService
- the endpoint service that we will front.Method Detail |
---|
protected void finalize() throws Throwable
finalize
in class Object
Throwable
public void init(PeerGroup peerGroup, ID id, Advertisement implAdv)
init
in interface Module
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.public int startApp(String[] arg)
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
startApp
in interface Module
arg
- An array of Strings forming the parameters for this
Module.
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.public void stopApp()
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.
stopApp
in interface Module
public ModuleImplAdvertisement getImplAdvertisement()
getImplAdvertisement
in interface Service
ModuleImplAdvertisement
.public EndpointService getInterface()
getInterface
in interface Service
public PeerGroup getGroup()
getGroup
in interface EndpointService
public Messenger getCanonicalMessenger(EndpointAddress addr, Object hint)
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.
getCanonicalMessenger
in interface EndpointService
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.
null
if no
local transport handles this type address.public Messenger getMessengerImmediate(EndpointAddress addr, Object hint)
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.
getMessengerImmediate
in interface EndpointService
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.
null
if the address is not handled by any of the available Message Transports.
The messenger, if returned, is not necessarily functional, nor resolved.ChannelMessenger
public Messenger getMessenger(EndpointAddress addr)
getMessenger
in interface EndpointService
addr
- the destination address.
null
is returned if the destination
address is not reachable.public Messenger getMessenger(EndpointAddress addr, Object hint)
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.
getMessenger
in interface EndpointService
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.
null
if the destination address is not reachable.public void propagate(Message msg, String serviceName, String serviceParam)
propagate
in interface EndpointService
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
.public void propagate(Message msg, String serviceName, String serviceParam, int initialTTL)
propagate
in interface EndpointService
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.public void demux(Message msg)
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.
demux
in interface EndpointService
msg
- The message to be delivered.public void processIncomingMessage(Message message, EndpointAddress source, EndpointAddress destination)
processIncomingMessage
in interface EndpointListener
message
- Incoming messagesource
- Endpoint Address of the source of the message.destination
- Endpoint Address of the destination of the message.@Deprecated public boolean ping(EndpointAddress addr)
ping
in interface EndpointService
addr
- is the Endpoint Address to ping.
true
if the address can be reached otherwise false
.public MessengerEventListener addMessageTransport(MessageTransport transpt)
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
.
addMessageTransport
in interface EndpointService
transpt
- the MessageTransport to be installed.
null
if the MessageTransport was not installed.public boolean removeMessageTransport(MessageTransport transpt)
stopApp()
and allow it to call
this method.
removeMessageTransport
in interface EndpointService
transpt
- the MessageTransport to be removed.
true
if the Message Transport was removed, otherwise
false
.public Iterator<MessageTransport> getAllMessageTransports()
getAllMessageTransports
in interface EndpointService
public MessageTransport getMessageTransport(String name)
getMessageTransport
in interface EndpointService
name
- The protocol name of the MessageTransport.
null
if there is no matching Message Transportpublic boolean addIncomingMessageListener(EndpointListener listener, String serviceName, String serviceParam)
null
.
addIncomingMessageListener
in interface EndpointService
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.
public EndpointListener getIncomingMessageListener(String serviceName, String serviceParam)
getIncomingMessageListener
in interface EndpointService
serviceName
- The service name to which the listener is registered.serviceParam
- The service parameter to which the listener is
registered. May be null
.
null
if there is no
listener for the specified name and parameter.public void addIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
null
.null
.null
.
addIncomingMessageFilterListener
in interface EndpointService
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.public void addOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
null
.null
.null
.
addOutgoingMessageFilterListener
in interface EndpointService
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.public MessageFilterListener removeIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
removeIncomingMessageFilterListener
in interface EndpointService
listener
- the listener to removenamespace
- the name spacename
- the name
public MessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
removeOutgoingMessageFilterListener
in interface EndpointService
listener
- the listener to removenamespace
- the name spacename
- the name
public EndpointListener removeIncomingMessageListener(String serviceName, String serviceParam)
removeIncomingMessageListener
in interface EndpointService
serviceName
- The service name to which the listener is registered.serviceParam
- The service parameter to which the listener is
registered. May be null
.
null
if there was
no listener for the specified name and parameter.public boolean addMessengerEventListener(MessengerEventListener listener, int prio)
addMessengerEventListener
in interface EndpointService
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.
public boolean removeMessengerEventListener(MessengerEventListener listener, int prio)
removeMessengerEventListener
in interface EndpointService
listener
- The listener that would have been called.prio
- Priority set from which to remove this listener.
@Deprecated public boolean getMessenger(MessengerEventListener listener, EndpointAddress addr, Object hint)
getMessenger
in interface EndpointService
listener
- the listener to call when the messenger is ready.addr
- the destination for the messenger.hint
- the messenger hint, if any, otherwise null.
true
if the messenger is queued for construction
otherwise false
.public Messenger getDirectMessenger(EndpointAddress addr, Object hint, boolean exclusive)
getDirectMessenger
in interface EndpointService
addr
- the destination address.hint
- the messenger hint, if any, otherwise null.exclusive
- if true avoids caching the messenger
null
is returned if the destination address is not reachable.
|
JXSE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |