|
Project 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
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
|
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 |
---|
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 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.
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.
EndpointAddress
,
ChannelMessenger
Messenger getMessenger(EndpointAddress addr, Object hint)
getMessengerImmediate(EndpointAddress, Object)
, except that the invoker is blocked until the
messenger resolves or fails to do so.
addr
- the destination address.hint
- A hint if there is one. Null, otherwise.
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.
Messenger
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 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.
void propagate(Message srcMsg, String serviceName, String serviceParam) throws IOException
srcMsg
- the message to be propagated.serviceName
- a destination service nameserviceParam
- a destination queue name within that service
IOException
- if the message could not be propagatedboolean ping(EndpointAddress addr)
addr
- is the Endpoint Address to ping.
boolean addIncomingMessageListener(EndpointListener listener, String serviceName, String serviceParam)
listener
- the listenerserviceName
- 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.
EndpointListener removeIncomingMessageListener(String serviceName, String serviceParam)
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.
void addIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
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)
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.MessageFilterListener removeIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
listener
- the listener that was registeredMessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name)
listener
- the listener that was registeredvoid demux(Message msg)
msg
- The message to be delivered.MessengerEventListener addMessageTransport(MessageTransport transpt)
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
.
transpt
- the MessageTransport to be installed.
boolean removeMessageTransport(MessageTransport transpt)
stopApp()
and allow it to call this method.
transpt
- the MessageTransport to be removed.
Iterator getAllMessageTransports()
MessageTransport getMessageTransport(String name)
name
- The name of the MessageTransport
Messenger getMessenger(EndpointAddress addr)
getMessenger(addr, null)
addr
- the destination address.
EndpointAddress
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.
|
JXTA J2SE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |