Project JXTA

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

Field Summary
static int DEFAULT_TTL
          Perform propagate() or walk() using the most appropriate TTL value for the implementation and configuration.
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_OK
 
Method Summary
 void addListener(RendezvousListener listener)
          Add a listener for RendezVousEvents
 boolean addPropagateListener(String name, EndpointListener listener)
          Deprecated. The naming convention is contrary to the more recent usage of specifying listeners with separate serviceName and serviceParam. Prefer addPropagateListener(String, String, EndpointListener).
 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.
 void challengeRendezVous(ID peer, long timeout)
          Set a new deadline for the rendezvous to be proven alive.
 void connectToRendezVous(EndpointAddress addr)
          Attempt connection to the specified peer as a new RendezVous point.
 void connectToRendezVous(PeerAdvertisement adv)
          Add a peer as a new RendezVousService point.
 void disconnectFromRendezVous(ID peerID)
          Disconnect from the specified rendezvous
 Vector getConnectedPeerIDs()
          Returns a Vector of PeerID of the peers that are currentely connected.
 Enumeration getConnectedPeers()
          Returns an Enumeration of PeerID of the peers that are currentely connected.
 Enumeration getConnectedRendezVous()
          Returns an Enumeration of the PeerID all the RendezVous on which this Peer is currentely connected.
 Enumeration getDisconnectedRendezVous()
          Returns an Enumeration of the PeerID all the RendezVous on which this Peer failed to connect to.
 Vector getLocalWalkView()
          Returns a vector of RdvAdvertisement of the local view of rendezvous peers.
 RendezVousStatus getRendezVousStatus()
          Returns the current status of this peer within the current group.
 boolean isConnectedToRendezVous()
          Return true if connected to a rendezvous.
 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.
 void propagate(Enumeration destPeerIds, Message msg, String serviceName, String serviceParam, int ttl)
          Propagates a message to the specified peers.
 void propagate(Message msg, String serviceName, String serviceParam, int ttl)
          Propagates a message to the local network and to as many members of the peer group as possible.
 void propagateInGroup(Message msg, String serviceName, String serviceParam, int ttl)
          Propagates a message to as many members of the peer group as possible.
 void propagateInGroup(Message msg, String serviceName, String serviceParam, int ttl, String prunePeer)
          Deprecated. no need to specify prune peer
 void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int ttl)
          Propagates a message to members of the peer group reachable via the local network.
 void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int ttl, String prunePeer)
          Deprecated. no need to specify prune peer
 boolean removeListener(RendezvousListener listener)
          Removes a Listener previously added with addListener.
 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).
 EndpointListener removePropagateListener(String serviceName, String serviceParam, EndpointListener listener)
          Removes a Listener previously added with addPropagateListener.
 boolean setAutoStart(boolean auto)
          Enable or disable the automatic switching between an Edge Peer and a Rendezvous Peer.
 boolean setAutoStart(boolean auto, long period)
          Enable or disable the automatic switching between an Edge Peer and a Rendezvous Peer.
 void startRendezVous()
          Start the local peer as a RendezVous peer with the default manager.
 void stopRendezVous()
          Stop the RendezVous function on the local Peer.
 void walk(Message msg, String serviceName, String serviceParam, int ttl)
          Walk a message through the rendezvous peers of the network: only rendezvous peers will receive the message.
 void walk(Vector destPeerIDs, Message msg, String serviceName, String serviceParam, int ttl)
          

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

 
Methods inherited from interface net.jxta.service.Service
getImplAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Module
init, startApp, stopApp
 

Field Detail

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
Method Detail

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.

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

JXTA J2SE