JXTA

net.jxta.rendezvous
Interface RendezVousService

All Superinterfaces:
Module, Service

public interface RendezVousService
extends Service

The RendezVous Service provides propagation of messages within a JXTA PeerGroup.

The JXTA RendezVous Service defines a subscription mechanism allowing JXTA peers to receive propagated messages (clients of the service) or become a repeater of the service (rendezvous peers).

The Standard Reference Implementation requires that at least one peer in a PeerGroup to act as a Rendezvous. Rendezvous peers may dynamically join or leave the PeerGroup over time.

See Also:
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_DISABLED, START_OK
 
Method Summary
 void addListener(RendezvousListener listener)
          Add a listener for RendezVousEvents.
 boolean addPropagateListener(String serviceName, String serviceParam, EndpointListener listener)
          Deprecated. This method just calls EndpointService.addIncomingMessageListener(net.jxta.endpoint.EndpointListener, java.lang.String, java.lang.String). It's better to just register your listener with the Endpoint. This call may be eventually removed.
 void challengeRendezVous(ID peer, long timeout)
          Set a new deadline for the rendezvous to be proven alive.
 void connectToRendezVous(EndpointAddress addr)
          Deprecated. Directly connecting to rendezvous peers is not recommended. Seed rendezvous should be specified using the RdvConfigAdv mechanisms.
 void connectToRendezVous(PeerAdvertisement adv)
          Deprecated. Directly connecting to rendezvous peers is not recommended. Seed rendezvous should be specified using the RdvConfigAdv mechanisms.
 void disconnectFromRendezVous(ID peerID)
          Disconnect from the specified rendezvous.
 Vector<ID> getConnectedPeerIDs()
          Returns a Vector of the PeerID of the peers that are currently connected to this peer.
 Enumeration<ID> getConnectedPeers()
          Returns an Enumeration of the PeerID of the peers that are currently connected to this peer.
 Enumeration<ID> getConnectedRendezVous()
          Returns an Enumeration of the PeerID all the RendezVous on which this Peer is currently connected.
 Enumeration<ID> getDisconnectedRendezVous()
          Deprecated. Due to design changes this no longer returns accurate nor complete results. It will eventually be removed.
 Vector<RdvAdvertisement> getLocalWalkView()
          Deprecated. Due to design changes, the list of peers may be empty in configurations which previously returned a non-empty result. Future JXTA versions are likely to use a different API.
 RendezVousStatus getRendezVousStatus()
          Returns the current role of this peer within the peergroup.
 boolean isConnectedToRendezVous()
          Return true if connected to a rendezvous.
 boolean isRendezVous()
          Returns true if this peer is acting as a rendezvous peer (per the implementation definition) within the peer group.
 void propagate(Enumeration<? extends ID> 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 propagateToNeighbors(Message msg, String serviceName, String serviceParam, int ttl)
          Propagates a message to members of the peer group reachable via the local network.
 boolean removeListener(RendezvousListener listener)
          Removes a Rendezvous event listener previously added with addListener.
 EndpointListener removePropagateListener(String serviceName, String serviceParam, EndpointListener listener)
          Deprecated. This method just calls EndpointService.removeIncomingMessageListener(java.lang.String, java.lang.String). It's better to just deregister your listener with the Endpoint. This call may be eventually removed.
 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.
 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<? extends ID> 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

@Deprecated
void connectToRendezVous(PeerAdvertisement adv)
                         throws IOException
Deprecated. Directly connecting to rendezvous peers is not recommended. Seed rendezvous should be specified using the RdvConfigAdv mechanisms.

Attempt connection to the specified RendezVous peer.

Parameters:
adv - the advertisement of the RendezVousService peer
Throws:
IOException - When the specified peer is unreachable

connectToRendezVous

@Deprecated
void connectToRendezVous(EndpointAddress addr)
                         throws IOException
Deprecated. Directly connecting to rendezvous peers is not recommended. Seed rendezvous should be specified using the RdvConfigAdv mechanisms.

Attempt connection to the specified RendezVous peer.

Parameters:
addr - EndpointAddress of the rendezvous peer
Throws:
IOException - When the specified peer is unreachable

disconnectFromRendezVous

void disconnectFromRendezVous(ID peerID)
Disconnect from the specified rendezvous.

Parameters:
peerID - the PeerId of the RendezVous to disconnect from.

getConnectedRendezVous

Enumeration<ID> getConnectedRendezVous()
Returns an Enumeration of the PeerID all the RendezVous on which this Peer is currently connected. This returns the same result as getConnectedPeers().

Returns:
Enumeration enumeration of RendezVous.

getDisconnectedRendezVous

@Deprecated
Enumeration<ID> getDisconnectedRendezVous()
Deprecated. Due to design changes this no longer returns accurate nor complete results. It will eventually be removed.

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

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

startRendezVous

void startRendezVous()
Start the local peer as a RendezVous peer.


stopRendezVous

void stopRendezVous()
Stop the RendezVous function on the local Peer. All connected Peers are disconnected.


getConnectedPeers

Enumeration<ID> getConnectedPeers()
Returns an Enumeration of the PeerID of the peers that are currently connected to this peer. Depending upon the role of of this peer the result may be an enumeration of clients or an enumeration of rendezvous peers.

Returns:
Enumeration of PeerID connected to this peer.

getConnectedPeerIDs

Vector<ID> getConnectedPeerIDs()
Returns a Vector of the PeerID of the peers that are currently connected to this peer. Depending upon the role of of this peer the result may be an enumeration of clients or an enumeration of rendezvous peers.

Returns:
Vector of PeerID connected to this peer.

addPropagateListener

@Deprecated
boolean addPropagateListener(String serviceName,
                                        String serviceParam,
                                        EndpointListener listener)
Deprecated. This method just calls EndpointService.addIncomingMessageListener(net.jxta.endpoint.EndpointListener, java.lang.String, java.lang.String). It's better to just register your listener with the Endpoint. This call may be eventually removed.

Registers the provided listener under the given serviceName and serviceParam to receive messages propagated by the Rendezvous service. The 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

@Deprecated
EndpointListener removePropagateListener(String serviceName,
                                                    String serviceParam,
                                                    EndpointListener listener)
Deprecated. This method just calls EndpointService.removeIncomingMessageListener(java.lang.String, java.lang.String). It's better to just deregister your listener with the Endpoint. This call may be eventually removed.

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 registered.

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 Rendezvous event listener previously added with addListener.

Parameters:
listener - the RendezvousListener listener remove
Returns:
true if successful

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 propagation is very expensive and should be used very cautiously. 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 appropriate.

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 - if an io error occurs

propagate

void propagate(Enumeration<? extends ID> destPeerIds,
               Message msg,
               String serviceName,
               String serviceParam,
               int ttl)
               throws IOException
Propagates a message to the specified peers.

Parameters:
destPeerIds - An enumeration of PeerIDs of the peers that are the intended recipients of the propagated message.
msg - The message to propagate.
serviceName - The name of the service.
serviceParam - The parameter of the service.
ttl - The requested TTL for the message.
Throws:
IOException - if an io error occurs

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 appropriate.

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 - if an io error occurs

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 appropriate.

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 - if an io error occurs

isConnectedToRendezVous

boolean isConnectedToRendezVous()
Return true if connected to a rendezvous.

Returns:
true if connected to a rendezvous otherwise false.

isRendezVous

boolean isRendezVous()
Returns true if this peer is acting as a rendezvous peer (per the implementation definition) within the peer group. false is returned for all other peer roles.

Returns:
true if this peer is acting as a rendezvous peer (per the implementation definition) within the peer group. false is returned for all other peer roles.

getRendezVousStatus

RendezVousStatus getRendezVousStatus()
Returns the current role of this peer within the peergroup.

Returns:
The current role of this peer within the peergroup.

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 role switching.
Returns:
The previous auto start value.

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 role switching.
period - The interval in milliseconds at which the peer should reconsider it's role.
Returns:
The previous auto start value.

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 appropriate.

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.
Throws:
IOException - when walking the message is impossible (network failure)

walk

void walk(Vector<? extends ID> 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 appropriate.

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.
Throws:
IOException - when walking the message is impossible (network failure)

getLocalWalkView

@Deprecated
Vector<RdvAdvertisement> getLocalWalkView()
Deprecated. Due to design changes, the list of peers may be empty in configurations which previously returned a non-empty result. Future JXTA versions are likely to use a different API.

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

Returns:
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 response must be sought and obtained within the specified delay or the rdv is considered disconnected.

A timeout of 0 or less triggers immediate disconnection.

Parameters:
peer - The peer to be challenged
timeout - The delay

JXSE