net.jxta.endpoint
Interface EndpointService

All Superinterfaces:

Module, Service

public interface EndpointService

extends Service

The EndpointService Service provides a frontend API and enviroment to all endpoint protocols. Applications can use the Endpoint API directely if they need to understand and control the topology of the JXTA network. In general, application are not expected to use this API.

Since:

JXTA 1.0

Method Summary

void	addFilterListener(java.lang.String elementName, EndpointFilterListener listener, boolean incoming) Registers an incoming messages filter listener.
void	addListener(java.lang.String address, EndpointListener listener) Registers an incoming messages listener.
boolean	addMessageTransport(MessageTransport transpt) Adds the specified MessageTransport to this endpoint.
void	demux(NewMessage msg) Handles the given incoming message by calling the listener specified by its destination as returned by the getDestAddress() method of the message.
java.util.Iterator	getAllMessageTransports() Get an iterator of the MessageTransports available to this EndpointService.
PeerGroup	getGroup() Returns the group to which this EndpointServiceImpl is attached.
EndpointMessenger	getMessenger(EndpointAddress addr) Builds and returns an EndpointMessager that may be used to send messages via this endpoint to the given destination
EndpointAddress	newEndpointAddress(java.lang.String Uri) Builds an EndpointAddress out the the given URI string.
Message	newMessage() Returns a new Message object suitable for use with this endpoint service.
boolean	ping(EndpointAddress addr) Verifies that the given address can be reached.
void	propagate(Message srcMsg, java.lang.String serviceName, java.lang.String serviceParam) Propagates the given message through all the endpoint protocols that are available to this endpoint.
void	propagate(NewMessage srcMsg, java.lang.String serviceName, java.lang.String serviceParam) Propagates the given message through all the endpoint protocols that are available to this endpoint.
void	removeFilterListener(java.lang.String address, EndpointFilterListener listener, boolean incoming) Removes the given listener previously registered under the given element name
boolean	removeListener(java.lang.String address, EndpointListener listener) Removes the given listener previously registered under the given address.
boolean	removeMessageTransport(MessageTransport transpt) Removes the given MessageTransport protocol from this endpoint service.

Methods inherited from interface net.jxta.service.Service

getImplAdvertisement, getInterface

Methods inherited from interface net.jxta.platform.Module

init, startApp, stopApp

Method Detail

getGroup

public PeerGroup getGroup()

Returns the group to which this EndpointServiceImpl is attached.

Returns:

PeerGroup the group.

newMessage

public Message newMessage()

Returns a new Message object suitable for use with this endpoint service.

Returns:

Message the new message.

newEndpointAddress

public EndpointAddress newEndpointAddress(java.lang.String Uri)

Builds an EndpointAddress out the the given URI string. The resulting EndpointAddress uniquely identifies a message listener at a given network address.

Parameters:

Uri - the uri. The structure of the Uri is as follows: protocol://address/[serviceName][/serviceParam]

Returns:

EndpointAddress the EndpointAddress object corresponding to the given URI.

getMessenger

public EndpointMessenger getMessenger(EndpointAddress addr)
                               throws java.io.IOException

Builds and returns an EndpointMessager that may be used to send messages via this endpoint to the given destination

Parameters:

addr - the destination address. This address specifies an endpoint protocol, the address of a peer by that endpoint protocol, and a serviceName and serviceParam, the concatenation of which designates uniquely the listener to which the messages must be delivered on arrival.

Returns:

EndpointMessenger the messenger. null is returned if the destination address is not reachable.

Throws:

java.io.IOException - is thrown if a network problem happened.

See Also:

EndpointAddress

propagate

public void propagate(Message srcMsg,
                      java.lang.String serviceName,
                      java.lang.String serviceParam)
               throws java.io.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.

Parameters:

srcMsg - the message to be propagated.

serviceName - a destination service name

serviceParam - a destination queue name within that service

Throws:

java.io.IOException - if the message could not be propagated

propagate

public void propagate(NewMessage srcMsg,
                      java.lang.String serviceName,
                      java.lang.String serviceParam)
               throws java.io.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.

Parameters:

srcMsg - the message to be propagated.

serviceName - a destination service name

serviceParam - a destination queue name within that service

Throws:

java.io.IOException - if the message could not be propagated

ping

public boolean ping(EndpointAddress addr)

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.

addListener

public void addListener(java.lang.String address,
                        EndpointListener listener)

Registers an incoming messages listener.

Each incoming message addressed to the queue specified by the given address will be passed to the given listener. The address is usually formed by concatenating the the name of the invoking service and a parameter unique to that service accross all groups (the group ID is normally included for that purpose).

For a message to match this address, it must have been sent through an EndpointMessenger obtained by providing an EndpointAddress constructed with matching serviceName and serviceParam (see newEndpointAddress and getMessenger), or by invoking propagate with matching serviceName and serviceParam.

If a listener is already registered with the given address, an IllegalArgumentException is thrown.

Parameters:

address - a queue name, unique accross all groups on this peer,

listener - a listener for these messages.

removeListener

public boolean removeListener(java.lang.String address,
                              EndpointListener listener)

Removes the given listener previously registered under the given address.

Parameters:

address - Endpoint Address associated to the listener.

listener - a listener to remove.

Returns:

boolean true is there was such a registration, false otherwise.

addFilterListener

public void addFilterListener(java.lang.String elementName,
                              EndpointFilterListener listener,
                              boolean incoming)
                       throws java.lang.IllegalArgumentException

Registers an incoming messages filter listener.

Each incoming message which contains an element with the specified name will be passed to the given listener. If a listener is already registered with the given address, an IllegalArgumentException is thrown.

Parameters:

elementName - The name is either a qualified element name containing a namespace and an element name or a namespace alone. A colon is used to seperate the namespace and element name.

listener - a listener for these messages.

incoming - whether to run the filter on the incoming or outgoing messages.

Throws:

java.lang.IllegalArgumentException - is thrown when one of the argument is illegal.

removeFilterListener

public void removeFilterListener(java.lang.String address,
                                 EndpointFilterListener listener,
                                 boolean incoming)

Removes the given listener previously registered under the given element name

Parameters:

address - the address the listener was registered for

listener - the listener that was registered

incoming - whether it was registered for incoming or outgoing messages.

demux

public void demux(NewMessage msg)
           throws java.io.IOException

Handles the given incoming message by calling the listener specified by its destination as returned by the getDestAddress() method of the message.

If the message cannot be delivered an IOException is thrown.

Parameters:

msg - The message to be delivered.

Throws:

java.io.IOException - when demux was not able to process the incoming message.

addMessageTransport

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

return - true if the MessageTransport was installed otherwise false.

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.

When to stop a transport is not all that easy to figure out, since the same MessageTransport object may be present in several groups. conclusion: Don't do it if you don't know what you're doing.

Parameters:

transpt - the MessageTransport to be removed.

Returns:

boolean true if the transport was removed, otherwise false.

getAllMessageTransports

public java.util.Iterator getAllMessageTransports()

Get an iterator of the MessageTransports available to this EndpointService.

Returns:

the iterator of all message transports.