|
JXTA | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface EndpointService
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 |
---|
static final int LowPrecedence
static final int MediumPrecedence
static final int HighPrecedence
Method Detail |
---|
PeerGroup getGroup()
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.
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
Messenger getMessenger(EndpointAddress addr, Object hint)
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.
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.Messenger getCanonicalMessenger(EndpointAddress addr, Object hint)
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.
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.boolean removeMessengerEventListener(MessengerEventListener listener, int priority)
listener
- The listener that would have been called.priority
- Priority set from which to remove this listener.
boolean addMessengerEventListener(MessengerEventListener listener, int priority)
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.
void propagate(Message message, String serviceName, String serviceParam) throws IOException
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
.
IOException
- Thrown if the message could not be propagated.void propagate(Message message, String serviceName, String serviceParam, int initialTTL)
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.@Deprecated boolean ping(EndpointAddress addr)
getMessenger()
is a better approach because the resulting Messenger is generally needed
soon after ping.
addr
- is the Endpoint Address to ping.
true
if the address can be reached otherwise false
.boolean addIncomingMessageListener(EndpointListener listener, String serviceName, String serviceParam)
null
.
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.
EndpointListener getIncomingMessageListener(String serviceName, String serviceParam)
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.EndpointListener removeIncomingMessageListener(String serviceName, String serviceParam)
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.void addIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
null
.null
.null
.
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.void addOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
null
.null
.null
.
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.MessageFilterListener removeIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
listener
- the listener to removenamespace
- the name spacename
- the name
MessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
listener
- the listener to removenamespace
- the name spacename
- the name
@Deprecated void demux(Message msg)
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.
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.
msg
- The message to be delivered.MessengerEventListener addMessageTransport(MessageTransport transport)
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
.
transport
- the MessageTransport to be installed.
null
if the MessageTransport was not installed.boolean removeMessageTransport(MessageTransport transpt)
stopApp()
and allow it to call
this method.
transpt
- the MessageTransport to be removed.
true
if the Message Transport was removed, otherwise
false
.Iterator<MessageTransport> getAllMessageTransports()
MessageTransport getMessageTransport(String name)
name
- The protocol name of the MessageTransport.
null
if there is no matching Message TransportMessenger getMessenger(EndpointAddress addr)
addr
- the destination address.
null
is returned if the destination
address is not reachable.@Deprecated boolean getMessenger(MessengerEventListener listener, EndpointAddress addr, Object hint)
ListenerAdaptor
which emulates this functionality.
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
.Messenger getDirectMessenger(EndpointAddress addr, Object hint, boolean exclusive)
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.
IllegalArgumentException
- if hint is not of RouteAdvertisement, or PeerAdvertisement type.
|
JXSE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |