JXTA

net.jxta.impl.rendezvous
Class RendezVousServiceInterface

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

public class RendezVousServiceInterface
extends Object
implements RendezVousService

This class implements the RendezVousService interface.


Field Summary
(package private)  RendezVousServiceImpl impl
           
 
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
RendezVousServiceInterface(RendezVousServiceImpl theRealThing)
          The only authorized constructor.
 
Method Summary
 void addListener(RendezvousListener listener)
          Add a listener for RendezVousEvents.
 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.
 void disconnectFromRendezVous(ID rendezVous)
          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()
          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.
 Service 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()
          Deprecated. This is private for debugging and diagnostics only.
 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 pg, ID assignedID, Advertisement impl)
          Initialize the module, passing it its peer group and advertisement.
 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 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 defaultTTL)
          Propagates a message to as many members of the peer group as possible.
 void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int defaultTTL)
          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

impl

RendezVousServiceImpl impl
Constructor Detail

RendezVousServiceInterface

RendezVousServiceInterface(RendezVousServiceImpl theRealThing)
The only authorized constructor.

Parameters:
theRealThing - the wrapped service
Method Detail

getInterface

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

Since THIS is already such an object, it returns itself. FIXME: it is kind of absurd to have this method part of the interface but we do not want to define two levels of Service interface just for that.

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.

init

public void init(PeerGroup pg,
                 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.

FIXME: This is meaningless for the interface object; it is there only to satisfy the requirements of the interface that we implement. Ultimately, the API should define two levels of interfaces: one for the real service implementation and one for the interface object. Right now it feels a bit heavy to so that since the only different between the two would be init() and may-be getName().

Specified by:
init in interface Module
Parameters:
pg - 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.

This is here for temporary class hierarchy reasons. it is ALWAYS ignored. By definition, the interface object protects the real object's start/stop methods from being called

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.

This is here for temporary class hierarchy reasons. it is ALWAYS ignored. By definition, the interface object protects the real object's start/stop methods from being called

This request is currently ignored.

Specified by:
stopApp in interface Module

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 rendezVous)
Disconnect from the specified rendezvous.

Specified by:
disconnectFromRendezVous in interface RendezVousService
Parameters:
rendezVous - 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.

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

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.

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.

addListener

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

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.

propagateToNeighbors

public void propagateToNeighbors(Message msg,
                                 String serviceName,
                                 String serviceParam,
                                 int defaultTTL)
                          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.
defaultTTL - The requested TTL for the message.
Throws:
IOException - if an io error occurs

propagateInGroup

public void propagateInGroup(Message msg,
                             String serviceName,
                             String serviceParam,
                             int defaultTTL)
                      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
defaultTTL - The requested TTL for the message.
Throws:
IOException - if an io error occurs

isConnectedToRendezVous

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

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

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.

getPeerView

@Deprecated
public PeerView getPeerView()
Deprecated. This is private for debugging and diagnostics only.

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

Returns:
the peer view

getRendezvousProvider

@Deprecated
public 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