net.jxta.rendezvous
Interface RendezVousService

All Superinterfaces:

Module, Service

public interface RendezVousService
extends Service

This interface provides an API to the Jxta RendezVous Service.

The RendezVous Service is responsible for propagating messages within a JXTA PeerGroup.

While the internal protcol of diffusion is left to the implementation of the service, the JXTA RendezVous Service defines a subscribe mechanism allowing JXTA peers to receive propagated messages (clients of the service) or become a repeater of the service (rendezvous peers). At least one peer in a given PeerGroup must be a rendezvous. However, rendezvous peers can dynamically join or leave the PeerGroup.

When a peers becomes a rendezvous, it publishes a special advertisement, a RdvAdvertisement that can be found by other peers which are looking for a rendezvous in the PeerGroup.

See Also:

net.jxta.rendezvous.RendezVousManager, net.jxta.rendezvous.RendezVousMonitor, RdvAdvertisement, PeerAdvertisement, JXTA Protocols Specification : Rendezvous

DEFAULT_TTL

static final int DEFAULT_TTL

Perform propagate() or walk() using the most appropriate TTL value for the implementation and configuration. The message will almost certainly be sent with a TTL value much less than this value.

See Also:

Constant Field Values

connectToRendezVous

void connectToRendezVous(PeerAdvertisement adv)
                         throws IOException

Add a peer as a new RendezVousService point.

If/When the RendezVousService accepts the connection, the RendezVous service will invoke the RendezVousMonitor.

Parameters:

adv - the advertisement of the RendezVousService peer

Throws:

IOException - when the RendezVousService peer is not reachable

connectToRendezVous

void connectToRendezVous(EndpointAddress addr)
                         throws IOException

Attempt connection to the specified peer as a new RendezVous point.

If/When the RendezVous accepts the connection, the RendezVous service will invoke the RendezVousMonitor.

Parameters:

addr - EndpointAddress of the rendezvous peer

Throws:

IOException - when the RendezVous peer is not reachable

disconnectFromRendezVous

void disconnectFromRendezVous(ID peerID)

Disconnect from the specified rendezvous

Parameters:

peerID - the PeerId of the RendezVous to disconnect from.

getConnectedRendezVous

Enumeration getConnectedRendezVous()

Returns an Enumeration of the PeerID all the RendezVous on which this Peer is currentely connected.

Returns:

Enumeration enumeration of RendezVous

getDisconnectedRendezVous

Enumeration getDisconnectedRendezVous()

Returns an Enumeration of the PeerID all the RendezVous on which this Peer failed to connect to.

Returns:

Enumeration enumeration of RendezVous

startRendezVous

void startRendezVous()

Start the local peer as a RendezVous peer with the default manager.

stopRendezVous

void stopRendezVous()

Stop the RendezVous function on the local Peer. All connected Peer are disconnected.

getConnectedPeers

Enumeration getConnectedPeers()

Returns an Enumeration of PeerID of the peers that are currentely connected.

Returns:

Enumeration enumeration of peers connected to that rendezvous

getConnectedPeerIDs

Vector getConnectedPeerIDs()

Returns a Vector of PeerID of the peers that are currentely connected.

Returns:

Vector vector of peers connected to that rendezvous

addPropagateListener

boolean addPropagateListener(String name,
                             EndpointListener listener)
                             throws IOException

Deprecated. The naming convention is contrary to the more recent usage of specifying listeners with separate serviceName and serviceParam. Prefer addPropagateListener(String, String, EndpointListener).

Registers the given listener under the given name to receive messages propagated by the rendezvous service. The given listener will be added only if no other listener is already registered with these names.

For historical reasons the messages that will be received are those address to the ServiceName and ServiceParam pair such that this listener's name is equal to their concatenation. For example, if a message is propagated or walked to a service named "Cheese" with a service parameter of "Burger", it will be received by a propagate listener of name "CheeseBurger".

Although never documented, this method used to also attach the given listener to the endpoint service, using the entire provided name as the service name, and null as the service param. This implementation artifact no longer exists.

Parameters:

name - The name of the listener.

listener - An EndpointListener to process the message.

Returns:

true if listener was registered, otherwise false.

Throws:

IOException

addPropagateListener

boolean addPropagateListener(String serviceName,
                             String serviceParam,
                             EndpointListener listener)

Registers the given listener under the given serviceName and serviceParam to receive messages propagated by the rendezvous service. The given listener will be added only if no other listener is already registered with these names.

Parameters:

serviceName - The serviceName of the listener.

serviceParam - The serviceParam of the listener.

listener - An EndpointListener to process the message.

Returns:

true if listener was registered, otherwise false.

removePropagateListener

EndpointListener removePropagateListener(String name,
                                         EndpointListener listener)

Deprecated. The naming convention is contrary to the more recent usage of specifying listeners with separate serviceName and serviceParam. Prefer removePropagateListener(String, String, EndpointListener).

Removes a Listener previously added with addPropagateListener. If the given listener is not the one currently registered, nothing is removed.

Parameters:

name - The name of the listener.

listener - An EndpointListener to process the message.

Returns:

the listener removed, null if the listener was not removed.

removePropagateListener

EndpointListener removePropagateListener(String serviceName,
                                         String serviceParam,
                                         EndpointListener listener)

Removes a Listener previously added with addPropagateListener. If the given listener is not the one currently registered, nothing is removed.

Parameters:

serviceName - The serviceName of the listener.

serviceParam - The serviceParam of the listener.

listener - An EndpointListener to process the message.

Returns:

the listener removed, null if the listener was not removed.

addListener

void addListener(RendezvousListener listener)

Add a listener for RendezVousEvents

Parameters:

listener - An RendezvousListener to process the event.

removeListener

boolean removeListener(RendezvousListener listener)

Removes a Listener previously added with addListener.

Parameters:

listener - the RendezvousListener listener remove

propagate

void propagate(Message msg,
               String serviceName,
               String serviceParam,
               int ttl)
               throws IOException

Propagates a message to the local network and to as many members of the peer group as possible.

This method sends the message to all peers, rendezvous peers and edge peer. This method of propation is very expensive and should not be frequentely used. When rendezvous peers are used in order to cache index of data, it is more efficient to use the walk() method.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Parameters:

msg - is the message to propagate.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - The requested TTL for the message.

Throws:

IOException

propagate

void propagate(Enumeration destPeerIds,
               Message msg,
               String serviceName,
               String serviceParam,
               int ttl)
               throws IOException

Propagates a message to the specified peers.

This method sends the message to all peers, rendezvous peers and edge peer. This method of propation is very expensive and should not be frequentely used. When rendezvous peers are used in order to cache index of data, it is more efficient to use the walk() method.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Parameters:

destPeerIds - an enumeration of PeerIDs of the peers that are the intended recipients of the propgated message.

msg - is the message to propagate.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - The requested TTL for the message.

Throws:

IOException

propagateToNeighbors

void propagateToNeighbors(Message msg,
                          String serviceName,
                          String serviceParam,
                          int ttl,
                          String prunePeer)
                          throws IOException

Deprecated. no need to specify prune peer

Propagates a message to members of the peer group reachable via the local network. Typically this is accomplished by broadcasting or multicasting.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Parameters:

msg - is the message to propagate.

serviceName - is the name of the service

serviceParam - is the parameter of the service

prunePeer - is a peer to prune in the propagation.

ttl - The requested TTL for the message.

Throws:

IOException

propagateToNeighbors

void propagateToNeighbors(Message msg,
                          String serviceName,
                          String serviceParam,
                          int ttl)
                          throws IOException

Propagates a message to members of the peer group reachable via the local network. Typically this is accomplished by broadcasting or multicasting.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Parameters:

msg - is the message to propagate.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - The requested TTL for the message.

Throws:

IOException

propagateInGroup

void propagateInGroup(Message msg,
                      String serviceName,
                      String serviceParam,
                      int ttl,
                      String prunePeer)
                      throws IOException

Deprecated. no need to specify prune peer

Propagates a message to as many members of the peer group as possible.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Parameters:

msg - is the message to propagate.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - The requested TTL for the message.

prunePeer - is a peer to prune in the propagation.

Throws:

IOException

propagateInGroup

void propagateInGroup(Message msg,
                      String serviceName,
                      String serviceParam,
                      int ttl)
                      throws IOException

Propagates a message to as many members of the peer group as possible.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Parameters:

msg - is the message to propagate.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - The requested TTL for the message.

Throws:

IOException

isConnectedToRendezVous

boolean isConnectedToRendezVous()

Return true if connected to a rendezvous.

Returns:

true if connected to a rendezvous, false otherwise

isRendezVous

boolean isRendezVous()

tells whether this rendezvous service currently acts as a "super-node" "rendezvous", knowlege hub, influence broker, or whichever higher status applies to the implementation.

Returns:

boolean true if this rendezvous acts as a "rendezvous" per the implementation definition.

getRendezVousStatus

RendezVousStatus getRendezVousStatus()

Returns the current status of this peer within the current group.

Returns:

the current status.

setAutoStart

boolean setAutoStart(boolean auto)

Enable or disable the automatic switching between an Edge Peer and a Rendezvous Peer.

Parameters:

auto - true will activate automatic switching

Returns:

the previous value of this mode

setAutoStart

boolean setAutoStart(boolean auto,
                     long period)

Enable or disable the automatic switching between an Edge Peer and a Rendezvous Peer.

Parameters:

auto - true will activate automatic switching

period - the period of auto-checking

Returns:

the previous value of this mode

walk

void walk(Message msg,
          String serviceName,
          String serviceParam,
          int ttl)
          throws IOException

Walk a message through the rendezvous peers of the network: only rendezvous peers will receive the message.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Note: The original msg is not modified and may be reused upon return.

Parameters:

msg - is the message to walk.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - is the maximum TTL of the message (note that the Rendezvous Service implementation is free to decrease that value.

Throws:

IOException - when walking the message is impossible (network failure)

walk

void walk(Vector destPeerIDs,
          Message msg,
          String serviceName,
          String serviceParam,
          int ttl)
          throws IOException

Walk a message through the rendezvous peers of the network: only rendezvous peers will receive the message.

Only a single HOP at a time is performed. Messages are always delivered to the destination handler on arrival. This handler is responsible for repropagating further, if deemed appropropriate.

Loop and TTL control are performed automatically.

Messages can be propagated via this method for the first time or can be re-propagated by re-using a message that came in via propagation. In the later case, the TTL and loop detection parameters CANNOT be re-initialized. If one wants to "re-propagate" a message with a new TTL and blank gateways list one must generate a completely new message. This limits the risk of accidental propagation storms, although they can always be engineered deliberately.

Note: The original msg is not modified and may be reused upon return.

Parameters:

destPeerIDs - is a Vector of PeerIDs of the peers which are receiving first the walker. Note that each entry in the Vector will create its own walker.

msg - is the message to walk.

serviceName - is the name of the service

serviceParam - is the parameter of the service

ttl - is the maximum TTL of the message (note that the Rendezvous Service implementation is free to decrease that value.

Throws:

IOException - when walking the message is impossible (network failure)

getLocalWalkView

Vector getLocalWalkView()

Returns a vector of RdvAdvertisement of the local view of rendezvous peers.

• Values are RdvAdvertisement.

Returns:

Vector containing RdvAdvertisement of the local view of RDV peers.

challengeRendezVous

void challengeRendezVous(ID peer,
                         long timeout)

Set a new deadline for the rendezvous to be proven alive. As a result a lease reponse must be sought and obtained within the specified delay or the rdv is considered disconnected. So, if a lease scheme is used, this can be implemented simply by setting the new lease deadLine accordingly.

A timeout of 0 or less triggers immediate disconnection.

Parameters:

peer - The peer to be challenged

timeout - The delay