JXTA

net.jxta.impl.rendezvous
Class RendezVousServiceProvider

java.lang.Object
  extended by net.jxta.impl.rendezvous.RendezVousServiceProvider
All Implemented Interfaces:
EndpointListener
Direct Known Subclasses:
AdhocPeerRdvService, StdRendezVousService

public abstract class RendezVousServiceProvider
extends Object
implements EndpointListener

This abstract class must be extended for all RendezVous Service providers that are managed by RendezVousServiceImpl.

Implementors of providers are responsible for using appropriate synchronization. The RendezvousServiceImpl provides synchronization control only only those methods which involve changing the active provider.


Field Summary
protected  boolean closed
           
protected  PeerGroup group
           
protected  int MAX_TTL
          Maximum TTL we will allow for propagation and repropagation issued by this peer.
protected  String PROP_HDR_ELEMENT_NAME
           
protected  String PropPName
           
protected static String PropSName
           
protected static String RDV_MSG_NAMESPACE_NAME
           
protected  RendezVousServiceImpl rdvService
           
protected  RendezvousMeter rendezvousMeter
           
protected  RendezvousServiceMonitor rendezvousServiceMonitor
           
 
Constructor Summary
protected RendezVousServiceProvider(PeerGroup group, RendezVousServiceImpl rdvService)
           
 
Method Summary
abstract  void challengeRendezVous(ID peer, long delay)
          Resets the local idea of the lease to the specified value.
protected  RendezVousPropagateMessage checkPropHeader(Message msg)
          Check and updates the header message element
abstract  void connectToRendezVous(EndpointAddress addr, Object hint)
          Attempt to connect to the specified rendezvous peer.
abstract  void disconnectFromRendezVous(ID peerID)
          Remove a RendezVousService point.
abstract  Vector<ID> getConnectedPeerIDs()
          Returns the peers that are currently connected to this peer.
protected  XMLDocument getPeerAdvertisementDoc()
           
protected  RendezVousPropagateMessage getPropHeader(Message msg)
          Get propagate header from the message.
abstract  boolean isConnectedToRendezVous()
          Return true if connected to a rendezvous.
protected static EndpointAddress mkAddress(ID destPeer, String serv, String parm)
          Convenience method for constructing an endpoint address from an id
protected static EndpointAddress mkAddress(String destPeer, String serv, String parm)
          Convenience method for constructing an endpoint address from an id
 void processIncomingMessage(Message msg, EndpointAddress srcAddr, EndpointAddress dstAddr)
          This method is invoked by the EndpointService for each incoming message which is addressed to this listener.
protected  void processReceivedMessage(Message message, RendezVousPropagateMessage propHdr, EndpointAddress srcAddr, EndpointAddress dstAddr)
          Process a propagated message.
abstract  void propagate(Enumeration<? extends ID> destPeerIds, Message msg, String serviceName, String serviceParam, int initialTTL)
          Propagates a message onto as many peers on the local network as possible.
abstract  void propagate(Message msg, String serviceName, String serviceParam, int initialTTL)
          Propagates a message onto as many peers on the local network as possible.
abstract  void propagateInGroup(Message msg, String serviceName, String serviceParam, int ttl)
           
abstract  void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int initialTTL)
          Propagates a message onto as many peers on the local network as possible.
protected abstract  void repropagate(Message msg, RendezVousPropagateMessage propHdr, String serviceName, String serviceParam)
          Responsible for forwarding received messages to the rest of the network as appropriate.
protected  void sendToNetwork(Message msg, RendezVousPropagateMessage propHdr)
          Propagates the message via endpoint propagation (multicast/broadcast) on all Message Transports.
 void setRendezvousServiceMonitor(RendezvousServiceMonitor rendezvousServiceMonitor)
          Set the RendezvousServiceMonitor.
protected  int startApp(String[] arg)
          Supply arguments and starts this service if it hadn't started by itself.
protected  void stopApp()
          Ask this service to stop.
protected  RendezVousPropagateMessage updatePropHeader(Message msg, RendezVousPropagateMessage propHdr, String serviceName, String serviceParam, int initialTTL)
           
abstract  void walk(Message msg, String serviceName, String serviceParam, int initialTTL)
          Walk a message through the rendezvous peers of the network: only rendezvous peers will receive the message.
abstract  void walk(Vector<? extends ID> destPeerIDs, Message msg, String serviceName, String serviceParam, int initialTTL)
          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

PropSName

protected static final String PropSName
See Also:
Constant Field Values

RDV_MSG_NAMESPACE_NAME

protected static final String RDV_MSG_NAMESPACE_NAME
See Also:
Constant Field Values

PropPName

protected final String PropPName

PROP_HDR_ELEMENT_NAME

protected final String PROP_HDR_ELEMENT_NAME

MAX_TTL

protected int MAX_TTL
Maximum TTL we will allow for propagation and repropagation issued by this peer.


group

protected final PeerGroup group

rdvService

protected final RendezVousServiceImpl rdvService

closed

protected boolean closed

rendezvousServiceMonitor

protected RendezvousServiceMonitor rendezvousServiceMonitor

rendezvousMeter

protected RendezvousMeter rendezvousMeter
Constructor Detail

RendezVousServiceProvider

protected RendezVousServiceProvider(PeerGroup group,
                                    RendezVousServiceImpl rdvService)
Parameters:
group - the peergroup
rdvService - the implementation
Method Detail

processIncomingMessage

public void processIncomingMessage(Message msg,
                                   EndpointAddress srcAddr,
                                   EndpointAddress dstAddr)
This method is invoked by the EndpointService for each incoming message which is addressed to this listener.

EndpointListener for the JxtaPropagate/

Specified by:
processIncomingMessage in interface EndpointListener
Parameters:
msg - Incoming message
srcAddr - Endpoint Address of the source of the message.
dstAddr - Endpoint Address of the destination of the message.

getPeerAdvertisementDoc

protected XMLDocument getPeerAdvertisementDoc()

startApp

protected int startApp(String[] arg)
Supply arguments and starts this service if it hadn't started by itself.

Currently this service starts by itself and does not expect arguments.

Parameters:
arg - argument params
Returns:
0 if successful

stopApp

protected void stopApp()
Ask this service to stop.


setRendezvousServiceMonitor

public void setRendezvousServiceMonitor(RendezvousServiceMonitor rendezvousServiceMonitor)
Set the RendezvousServiceMonitor. The RendezvousServiceMonitor is used to meter the activity of the RendezvousService.

Parameters:
rendezvousServiceMonitor - The monitor.
See Also:
MonitorManager

challengeRendezVous

public abstract void challengeRendezVous(ID peer,
                                         long delay)
Resets the local idea of the lease to the specified value. As a result a lease response must be sought and obtained within the new specified delay or the rdv is considered disconnected.

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

connectToRendezVous

public abstract void connectToRendezVous(EndpointAddress addr,
                                         Object hint)
                                  throws IOException
Attempt to connect to the specified rendezvous peer.

Parameters:
addr - The endpoint address of the rendezvous peer.
hint - An optional hint which may be null.
Throws:
IOException - If no connection could be made to the specified peer.

disconnectFromRendezVous

public abstract void disconnectFromRendezVous(ID peerID)
Remove a RendezVousService point.

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

getConnectedPeerIDs

public abstract Vector<ID> getConnectedPeerIDs()
Returns the peers that are currently connected to this peer.

Returns:
The peers that are currently connected to this peer.

propagate

public abstract void propagate(Message msg,
                               String serviceName,
                               String serviceParam,
                               int initialTTL)
                        throws IOException
Propagates a message onto as many peers on the local network as possible. Typically the message will go to all the peers to which at least one endpoint transport can address without using the router.

This method sends the message to all peers, rendezvous peers and edge peer. This method of propagation is very expensive and should not be frequently 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 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 propagate.
serviceName - is the name of the service
serviceParam - is the parameter of the service
initialTTL - is the maximum TTL of the message (note that the Rendezvous Service implementation is free to decrease that value.
Throws:
IOException - if an io error occurs

propagate

public abstract void propagate(Enumeration<? extends ID> destPeerIds,
                               Message msg,
                               String serviceName,
                               String serviceParam,
                               int initialTTL)
                        throws IOException
Propagates a message onto as many peers on the local network as possible. Typically the message will go to all the peers to which at least one endpoint transport can address without using the router.

This method sends the message to all peers, rendezvous peers and edge peer. This method of propagation is very expensive and should not be frequently 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 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 - An enumeration of the peers that are recipients of the propagated message.
msg - is the message to propagate.
serviceName - is the name of the service
serviceParam - is the parameter of the service
initialTTL - is the maximum TTL of the message (note that the Rendezvous Service implementation is free to decrease that value.
Throws:
IOException - if an io error occurs

propagateToNeighbors

public abstract void propagateToNeighbors(Message msg,
                                          String serviceName,
                                          String serviceParam,
                                          int initialTTL)
                                   throws IOException
Propagates a message onto as many peers on the local network as possible. Typically the message will go to all the peers to which at least one endpoint transport can address without using the router.

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 propagate.
serviceName - is the name of the service
serviceParam - is the parameter of the service
initialTTL - is the maximum TTL of the message (note that the Rendezvous Service implementation is free to decrease that value.
Throws:
IOException - if an io error occurs

isConnectedToRendezVous

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

Returns:
true if connected to a rendezvous, false otherwise

walk

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

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

processReceivedMessage

protected void processReceivedMessage(Message message,
                                      RendezVousPropagateMessage propHdr,
                                      EndpointAddress srcAddr,
                                      EndpointAddress dstAddr)
Process a propagated message.

Parameters:
message - the message received
propHdr - the message header
srcAddr - the source address
dstAddr - the message destination addreess

repropagate

protected abstract void repropagate(Message msg,
                                    RendezVousPropagateMessage propHdr,
                                    String serviceName,
                                    String serviceParam)
Responsible for forwarding received messages to the rest of the network as appropriate. This generally only makes sense for multicast or broadcast scenarios.

Parameters:
msg - the message to be repropagated.
propHdr - It's current propagation header.
serviceName - The destination service.
serviceParam - The destination service parameter.

propagateInGroup

public abstract void propagateInGroup(Message msg,
                                      String serviceName,
                                      String serviceParam,
                                      int ttl)
                               throws IOException
Throws:
IOException

sendToNetwork

protected void sendToNetwork(Message msg,
                             RendezVousPropagateMessage propHdr)
                      throws IOException
Propagates the message via endpoint propagation (multicast/broadcast) on all Message Transports.

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

Parameters:
msg - The message to be propagated.
propHdr - It's current propagation header.
Throws:
IOException - if an io error occurs

mkAddress

protected static EndpointAddress mkAddress(String destPeer,
                                           String serv,
                                           String parm)
Convenience method for constructing an endpoint address from an id

Parameters:
destPeer - peer id
serv - the service name (if any)
parm - the service param (if any)
Returns:
endpointAddress for this peer id.

mkAddress

protected static EndpointAddress mkAddress(ID destPeer,
                                           String serv,
                                           String parm)
Convenience method for constructing an endpoint address from an id

Parameters:
destPeer - peer id
serv - the service name (if any)
parm - the service param (if any)
Returns:
endpointAddress for this peer id.

getPropHeader

protected RendezVousPropagateMessage getPropHeader(Message msg)
Get propagate header from the message.

Parameters:
msg - The source message.
Returns:
The message's propagate header if any, otherwise null.

checkPropHeader

protected RendezVousPropagateMessage checkPropHeader(Message msg)
Check and updates the header message element

Parameters:
msg - the message to check
Returns:
an upadate message

updatePropHeader

protected RendezVousPropagateMessage updatePropHeader(Message msg,
                                                      RendezVousPropagateMessage propHdr,
                                                      String serviceName,
                                                      String serviceParam,
                                                      int initialTTL)

JXSE