JXTA

net.jxta.impl.rendezvous
Class RendezVousServiceImpl

java.lang.Object
  extended by net.jxta.impl.rendezvous.RendezVousServiceImpl
All Implemented Interfaces:
Module, RendezVousService, Service

public final class RendezVousServiceImpl
extends Object
implements RendezVousService

A JXTA RendezVousService implementation which implements the standard JXTA Rendezvous Protocol (RVP).

See Also:
RendezVousService, JXTA Protocols Specification : Rendezvous Protocol

Field Summary
 EndpointService endpoint
           
protected static int MAX_MSGIDS
           
 
Fields inherited from interface net.jxta.rendezvous.RendezVousService
DEFAULT_TTL
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_DISABLED, START_OK
 
Constructor Summary
RendezVousServiceImpl()
          Constructor for the RendezVousServiceImpl object
 
Method Summary
 void addListener(RendezvousListener listener)
          Add a listener for RendezVousEvents.
 boolean addMsgId(UUID id)
          Checks if a message id has been recorded.
 boolean addPropagateListener(String serviceName, String serviceParam, EndpointListener listener)
          Registers the provided listener under the given serviceName and serviceParam to receive messages propagated by the Rendezvous service.
 void challengeRendezVous(ID peer, long delay)
          Set a new deadline for the rendezvous to be proven alive.
 void connectToRendezVous(EndpointAddress addr)
          Attempt connection to the specified RendezVous peer.
 void connectToRendezVous(PeerAdvertisement adv)
          Attempt connection to the specified RendezVous peer.
 UUID createMsgId()
           
 void disconnectFromRendezVous(ID peerId)
          Disconnect from the specified rendezvous.
 void generateEvent(int type, ID regarding)
          Creates a rendezvous event and sends it to all registered listeners.
 ID getAssignedID()
          Return the assigned ID for this service.
 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()
          Returns an Enumeration of the PeerID all the RendezVous on which this Peer failed to connect to.
 ModuleImplAdvertisement getImplAdvertisement()
          Returns the advertisement for this service.
 RendezVousService getInterface()
          Service objects are not manipulated directly to protect usage of the service.
 Vector<RdvAdvertisement> getLocalWalkView()
          Returns a vector of RdvAdvertisement of the local view of rendezvous peers.
 PeerView getPeerView()
          Returns the PeerView
(package private)  RendezVousServiceProvider getRendezvousProvider()
          Deprecated. This is private for debugging and diagnostics only.
 RendezVousStatus getRendezVousStatus()
          Returns the current role of this peer within the peergroup.
 void init(PeerGroup g, ID assignedID, Advertisement impl)
          Initialize the module, passing it its peer group and advertisement.
 boolean isConnectedToRendezVous()
          Gets the rendezvousConnected attribute of the RendezVousServiceImpl object
 boolean isMsgIdRecorded(UUID id)
           
 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 defaultTTL)
          Propagates a message to the specified peers.
 void propagate(Message msg, String serviceName, String serviceParam, int defaultTTL)
          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)
          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.
 int startApp(String[] arg)
          Complete any remaining initialization of the module.
 void startRendezVous()
          Start the local peer as a RendezVous peer.
 void stopApp()
          Stop a module.
 void stopRendezVous()
          Stop the RendezVous function on the local Peer.
 void walk(Message msg, String serviceName, String serviceParam, int defaultTTL)
          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 defaultTTL)
          

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

 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_MSGIDS

protected static final int MAX_MSGIDS
See Also:
Constant Field Values

endpoint

public EndpointService endpoint
Constructor Detail

RendezVousServiceImpl

public RendezVousServiceImpl()
Constructor for the RendezVousServiceImpl object

Method Detail

getInterface

public RendezVousService getInterface()
Service objects are not manipulated directly to protect usage of the service. A Service interface is returned to access the service methods.

Specified by:
getInterface in interface Service
Returns:
Service public interface of the service

getImplAdvertisement

public ModuleImplAdvertisement getImplAdvertisement()
Returns the advertisement for this service.

Specified by:
getImplAdvertisement in interface Service
Returns:
Advertisement the advertisement. This is always a ModuleImplAdvertisement.

getAssignedID

public ID getAssignedID()
Return the assigned ID for this service.

Returns:
The assigned ID for this service.

init

public void init(PeerGroup g,
                 ID assignedID,
                 Advertisement impl)
Initialize the module, passing it its peer group and advertisement.

Note: when subclassing one of the existing PeerGroup implementations (which implement Module), it may not be recommended to overload the init method. See the documentation of the PeerGroup class being subclassed.

Note: it is permissible to pass null as the impl parameter when this instance is not being loaded via the module framework.

Specified by:
init in interface Module
Parameters:
g - The PeerGroup from which this Module can obtain services. If this module is a Service, this is also the PeerGroup of which this module is a service.
assignedID - Identity of Module within group. modules can use it as a the root of their namespace to create names that are unique within the group but predictable by the same module on another peer. This is normally the ModuleClassID which is also the name under which the module is known by other modules. For a group it is the PeerGroupID itself. The parameters of a service, in the Peer configuration, are indexed by the assignedID of that service, and a Service must publish its run-time parameters in the Peer Advertisement under its assigned ID.
impl - The implementation advertisement for this Module. It is permissible to pass null if no implementation advertisement is available. This may happen if the implementation was selected by explicit class name rather than by following an implementation advertisement. Modules are not required to support that style of loading, but if they do, then their documentation should mention it.

startApp

public int startApp(String[] arg)
Complete any remaining initialization of the module. The module should be fully functional after startApp() is completed. That is also the opportunity to supply arbitrary arguments (mostly to applications).

If this module is a PeerGroup service, it may be invoked several times depending on its return value.

Specified by:
startApp in interface Module
Parameters:
arg - An array of Strings forming the parameters for this Module.
Returns:
int A status indication which may be one of Module.START_OK, Module.START_AGAIN_PROGRESS, Module.START_AGAIN_STALLED, which indicates partial or complete success, or any other value (negative values are recommended for future compatibility), which indicates failure.

stopApp

public void stopApp()
Stop a module. This may be called any time after init() completes and should not assume that startApp() has been called or completed.

The Module cannot be forced to comply, but in the future we might be able to deny it access to anything after some timeout.

Specified by:
stopApp in interface Module

isRendezVous

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

Specified by:
isRendezVous in interface RendezVousService
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

public RendezVousStatus getRendezVousStatus()
Description copied from interface: net.jxta.rendezvous.RendezVousService
Returns the current role of this peer within the peergroup.

Specified by:
getRendezVousStatus in interface RendezVousService
Returns:
The current role of this peer within the peergroup.

setAutoStart

public boolean setAutoStart(boolean auto)
Enable or disable the automatic switching between an Edge Peer and a Rendezvous Peer.

Specified by:
setAutoStart in interface RendezVousService
Parameters:
auto - true will activate automatic role switching.
Returns:
The previous auto start value.

setAutoStart

public boolean setAutoStart(boolean auto,
                            long period)
Enable or disable the automatic switching between an Edge Peer and a Rendezvous Peer.

Specified by:
setAutoStart in interface RendezVousService
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.

connectToRendezVous

public void connectToRendezVous(PeerAdvertisement adv)
                         throws IOException
Attempt connection to the specified RendezVous peer.

Specified by:
connectToRendezVous in interface RendezVousService
Parameters:
adv - the advertisement of the RendezVousService peer
Throws:
IOException - When the specified peer is unreachable

connectToRendezVous

public void connectToRendezVous(EndpointAddress addr)
                         throws IOException
Attempt connection to the specified RendezVous peer.

Specified by:
connectToRendezVous in interface RendezVousService
Parameters:
addr - EndpointAddress of the rendezvous peer
Throws:
IOException - When the specified peer is unreachable

challengeRendezVous

public void challengeRendezVous(ID peer,
                                long delay)
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.

Specified by:
challengeRendezVous in interface RendezVousService
Parameters:
peer - The peer to be challenged
delay - The delay

disconnectFromRendezVous

public void disconnectFromRendezVous(ID peerId)
Disconnect from the specified rendezvous.

Specified by:
disconnectFromRendezVous in interface RendezVousService
Parameters:
peerId - the PeerId of the RendezVous to disconnect from.

getConnectedRendezVous

public 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 RendezVousService.getConnectedPeers().

Specified by:
getConnectedRendezVous in interface RendezVousService
Returns:
Enumeration enumeration of RendezVous.

getDisconnectedRendezVous

public Enumeration<ID> getDisconnectedRendezVous()
Returns an Enumeration of the PeerID all the RendezVous on which this Peer failed to connect to.

Specified by:
getDisconnectedRendezVous in interface RendezVousService
Returns:
Enumeration of the PeerID all the RendezVous on which this Peer failed to connect to.

getConnectedPeers

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

Specified by:
getConnectedPeers in interface RendezVousService
Returns:
Enumeration of PeerID connected to this peer.

getConnectedPeerIDs

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

Specified by:
getConnectedPeerIDs in interface RendezVousService
Returns:
Vector of PeerID connected to this peer.

isConnectedToRendezVous

public boolean isConnectedToRendezVous()
Gets the rendezvousConnected attribute of the RendezVousServiceImpl object

Specified by:
isConnectedToRendezVous in interface RendezVousService
Returns:
true if connected to a rendezvous, false otherwise

startRendezVous

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

Specified by:
startRendezVous in interface RendezVousService

stopRendezVous

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

Specified by:
stopRendezVous in interface RendezVousService

addPropagateListener

public boolean addPropagateListener(String serviceName,
                                    String serviceParam,
                                    EndpointListener listener)
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.

Specified by:
addPropagateListener in interface RendezVousService
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

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

Specified by:
removePropagateListener in interface RendezVousService
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.

propagate

public void propagate(Message msg,
                      String serviceName,
                      String serviceParam,
                      int defaultTTL)
               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.

Specified by:
propagate in interface RendezVousService
Parameters:
msg - is the message to propagate.
serviceName - is the name of the service.
serviceParam - is the parameter of the service.
defaultTTL - The requested TTL for the message.
Throws:
IOException - if an io error occurs

propagate

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

Specified by:
propagate in interface RendezVousService
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.
defaultTTL - The requested TTL for the message.
Throws:
IOException - if an io error occurs

walk

public void walk(Message msg,
                 String serviceName,
                 String serviceParam,
                 int defaultTTL)
          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.

Specified by:
walk in interface RendezVousService
Parameters:
msg - is the message to walk.
serviceName - is the name of the service
serviceParam - is the parameter of the service
defaultTTL - is the maximum TTL of the message.
Throws:
IOException - when walking the message is impossible (network failure)

walk

public void walk(Vector<? extends ID> destPeerIDs,
                 Message msg,
                 String serviceName,
                 String serviceParam,
                 int defaultTTL)
          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.

Specified by:
walk in interface RendezVousService
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
defaultTTL - is the maximum TTL of the message.
Throws:
IOException - when walking the message is impossible (network failure)

getLocalWalkView

public Vector<RdvAdvertisement> getLocalWalkView()
Returns a vector of RdvAdvertisement of the local view of rendezvous peers.

Specified by:
getLocalWalkView in interface RendezVousService
Returns:
The local view of RDV peers.

getPeerView

public PeerView getPeerView()
Returns the PeerView

Returns:
the PeerView

propagateToNeighbors

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

Specified by:
propagateToNeighbors in interface RendezVousService
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

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

Specified by:
propagateInGroup in interface RendezVousService
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

addListener

public final void addListener(RendezvousListener listener)
Add a listener for RendezVousEvents.

Specified by:
addListener in interface RendezVousService
Parameters:
listener - An RendezvousListener to process the event.

removeListener

public final boolean removeListener(RendezvousListener listener)
Removes a Rendezvous event listener previously added with addListener.

Specified by:
removeListener in interface RendezVousService
Parameters:
listener - the RendezvousListener listener remove
Returns:
true if successful

generateEvent

public final void generateEvent(int type,
                                ID regarding)
Creates a rendezvous event and sends it to all registered listeners.

Parameters:
type - event type
regarding - event peer ID

isMsgIdRecorded

public boolean isMsgIdRecorded(UUID id)

addMsgId

public boolean addMsgId(UUID id)
Checks if a message id has been recorded.

Parameters:
id - message to record.
Returns:
true If message was added otherwise (duplicate) false.

createMsgId

public UUID createMsgId()

getRendezvousProvider

@Deprecated
RendezVousServiceProvider getRendezvousProvider()
Deprecated. This is private for debugging and diagnostics only.

Get the current provider. This is for debugging purposes only.

Returns:
the provider

JXSE