sjero.net Git - linphone/blob - p2pproxy/dependencies-src/jxse-src-2.5/api/src/net/jxta/rendezvous/RendezVousService.java

   1 /*
   2  * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
   3  *
   4  *  The Sun Project JXTA(TM) Software License
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are met:
   8  *
   9  *  1. Redistributions of source code must retain the above copyright notice,
  10  *     this list of conditions and the following disclaimer.
  11  *
  12  *  2. Redistributions in binary form must reproduce the above copyright notice,
  13  *     this list of conditions and the following disclaimer in the documentation
  14  *     and/or other materials provided with the distribution.
  15  *
  16  *  3. The end-user documentation included with the redistribution, if any, must
  17  *     include the following acknowledgment: "This product includes software
  18  *     developed by Sun Microsystems, Inc. for JXTA(TM) technology."
  19  *     Alternately, this acknowledgment may appear in the software itself, if
  20  *     and wherever such third-party acknowledgments normally appear.
  21  *
  22  *  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
  23  *     not be used to endorse or promote products derived from this software
  24  *     without prior written permission. For written permission, please contact
  25  *     Project JXTA at http://www.jxta.org.
  26  *
  27  *  5. Products derived from this software may not be called "JXTA", nor may
  28  *     "JXTA" appear in their name, without prior written permission of Sun.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
  31  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  32  *  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
  33  *  MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  34  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  36  *  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  37  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  38  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  39  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  *
  41  *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United
  42  *  States and other countries.
  43  *
  44  *  Please see the license information page at :
  45  *  <http://www.jxta.org/project/www/license.html> for instructions on use of
  46  *  the license in source files.
  47  *
  48  *  ====================================================================
  49  *
  50  *  This software consists of voluntary contributions made by many individuals
  51  *  on behalf of Project JXTA. For more information on Project JXTA, please see
  52  *  http://www.jxta.org.
  53  *
  54  *  This license is based on the BSD license adopted by the Apache Foundation.
  55  */
  56
  57 package net.jxta.rendezvous;
  58
  59
  60 import java.io.IOException;
  61 import java.util.Enumeration;
  62 import java.util.Vector;
  63
  64 import net.jxta.endpoint.EndpointAddress;
  65 import net.jxta.endpoint.EndpointListener;
  66 import net.jxta.endpoint.Message;
  67 import net.jxta.id.ID;
  68 import net.jxta.protocol.PeerAdvertisement;
  69 import net.jxta.protocol.RdvAdvertisement;
  70 import net.jxta.service.Service;
  71
  72
  73 /**
  74  * The RendezVous Service provides propagation of messages within a JXTA
  75  * PeerGroup.
  76  *
  77  * <p/>The JXTA RendezVous Service defines a subscription mechanism
  78  * allowing JXTA peers to receive propagated messages (clients of the service)
  79  * or become a repeater of the service (rendezvous peers).
  80  *
  81  * <p/>The Standard Reference Implementation requires that at least one peer in
  82  * a PeerGroup to act as a Rendezvous. Rendezvous peers may dynamically join or
  83  * leave the PeerGroup over time.
  84  *
  85  * @see    <a href="https://jxta-spec.dev.java.net/nonav/JXTAProtocols.html#proto-rvp" target='_blank'>JXTA Protocols Specification : Rendezvous</a>
  86  */
  87 public interface RendezVousService extends Service {
  88
  89     /**
  90      *  Perform <code>propagate()</code> or <code>walk()</code> using the most
  91      *  appropriate TTL value for the implementation and configuration. The
  92      *  message will almost certainly be sent with a TTL value much less than
  93      *  this value.
  94      */
  95     public final static int DEFAULT_TTL = Integer.MAX_VALUE;
  96
  97     /**
  98      * Attempt connection to the specified RendezVous peer.
  99      *
 100      * @deprecated Directly connecting to rendezvous peers is not recommended.
 101      * Seed rendezvous should be specified using the RdvConfigAdv mechanisms.
 102      *
 103      * @param  adv           the advertisement of the RendezVousService peer
 104      * @throws  IOException  When the specified peer is unreachable
 105      */
 106     @Deprecated
 107     public void connectToRendezVous(PeerAdvertisement adv) throws IOException;
 108
 109     /**
 110      * Attempt connection to the specified RendezVous peer.
 111      *
 112      * @deprecated Directly connecting to rendezvous peers is not recommended.
 113      * Seed rendezvous should be specified using the RdvConfigAdv mechanisms.
 114      *
 115      * @param  addr          EndpointAddress of the rendezvous peer
 116      * @throws  IOException  When the specified peer is unreachable
 117      */
 118     @Deprecated
 119     public void connectToRendezVous(EndpointAddress addr) throws IOException;
 120
 121     /**
 122      * Disconnect from the specified rendezvous.
 123      *
 124      * @param  peerID  the PeerId of the RendezVous to disconnect from.
 125      */
 126     public void disconnectFromRendezVous(ID peerID);
 127
 128     /**
 129      * Returns an Enumeration of the PeerID all the RendezVous on which this
 130      * Peer is currently connected. This returns the same result as
 131      * {@link #getConnectedPeers()}.
 132      *
 133      * @return    Enumeration enumeration of RendezVous.
 134      */
 135     public Enumeration<ID> getConnectedRendezVous();
 136
 137     /**
 138      * Returns an Enumeration of the PeerID all the RendezVous on which this
 139      * Peer failed to connect to.
 140      *
 141      * @deprecated Due to design changes this no longer returns accurate nor
 142      * complete results. It will eventually be removed.
 143      *
 144      * @return    Enumeration of the PeerID all the RendezVous on which this
 145      * Peer failed to connect to.
 146      */
 147     @Deprecated
 148     public Enumeration<ID> getDisconnectedRendezVous();
 149
 150     /**
 151      * Start the local peer as a RendezVous peer.
 152      */
 153     public void startRendezVous();
 154
 155     /**
 156      * Stop the RendezVous function on the local Peer. All connected Peers are
 157      * disconnected.
 158      */
 159     public void stopRendezVous();
 160
 161     /**
 162      * Returns an Enumeration of the PeerID of the peers that are currently
 163      * connected to this peer. Depending upon the role of of this peer the
 164      * result may be an enumeration of clients or an enumeration of rendezvous
 165      * peers.
 166      *
 167      * @return Enumeration of {@link net.jxta.peer.PeerID} connected to this peer.
 168      */
 169     public Enumeration<ID> getConnectedPeers();
 170
 171     /**
 172      * Returns a Vector of the PeerID of the peers that are currently
 173      * connected to this peer. Depending upon the role of of this peer the
 174      * result may be an enumeration of clients or an enumeration of rendezvous
 175      * peers.
 176      *
 177      * @return Vector of {@link net.jxta.peer.PeerID} connected to this peer.
 178      */
 179     public Vector<ID> getConnectedPeerIDs();
 180
 181     /**
 182      * Registers the provided listener under the given serviceName and
 183      * serviceParam to receive messages propagated by the Rendezvous service.
 184      * The listener will be added only if no other listener is already
 185      * registered with these names.
 186      *
 187      * @deprecated This method just calls
 188      * {@link net.jxta.endpoint.EndpointService#addIncomingMessageListener}. It's better to just
 189      * register your listener with the Endpoint. This call <b>may</b> be
 190      * eventually removed.
 191      *
 192      * @param  serviceName   The serviceName of the listener.
 193      * @param  serviceParam  The serviceParam of the listener.
 194      * @param  listener      An EndpointListener to process the message.
 195      * @return               true if listener was registered, otherwise false.
 196      */
 197     @Deprecated
 198     public boolean addPropagateListener(String serviceName, String serviceParam, EndpointListener listener);
 199
 200     /**
 201      * Removes a Listener previously added with addPropagateListener.
 202      * If the given listener is not the one currently registered, nothing is removed.
 203      *
 204      * @deprecated This method just calls
 205      * {@link net.jxta.endpoint.EndpointService#removeIncomingMessageListener}.
 206      * It's better to just deregister your listener with the Endpoint. This call
 207      * <b>may</b> be eventually removed.
 208      *
 209      * @param  serviceName   The serviceName of the listener.
 210      * @param  serviceParam  The serviceParam of the listener.
 211      * @param  listener      An EndpointListener to process the message.
 212      * @return               the listener removed, <tt>null</tt> if the listener was not registered.
 213      */
 214     @Deprecated
 215     public EndpointListener removePropagateListener(String serviceName, String serviceParam, EndpointListener listener);
 216
 217     /**
 218      * Add a listener for RendezVousEvents.
 219      *
 220      * @param  listener  An RendezvousListener to process the event.
 221      */
 222     public void addListener(RendezvousListener listener);
 223
 224     /**
 225      * Removes a Rendezvous event listener previously added with addListener.
 226      *
 227      * @param  listener  the RendezvousListener listener remove
 228      * @return           true if successful
 229      */
 230     public boolean removeListener(RendezvousListener listener);
 231
 232     /**
 233      * Propagates a message to the local network and to as many members of
 234      * the peer group as possible.
 235      *
 236      * <p/>This method sends the message to all peers, rendezvous peers and
 237      * edge peer. This method of propagation is very expensive and should
 238      * be used very cautiously. When rendezvous peers are used in order to
 239      * cache index of data, it is more efficient to use the walk() method.
 240      *
 241      * <p/>Only a single HOP at a time is performed. Messages are always
 242      * delivered to the destination handler on arrival. This handler
 243      * is responsible for repropagating further, if deemed appropriate.
 244      *
 245      * <p/>Loop and TTL control are performed automatically.
 246      *
 247      * <p/>Messages can be propagated via this method for the first time or
 248      * can be re-propagated by re-using a message that came in via propagation.
 249      * In the later case, the TTL and loop detection parameters CANNOT be
 250      * re-initialized. If one wants to "re-propagate" a message with a new TTL
 251      * and blank gateways list one must generate a completely new message.
 252      * This limits the risk of accidental propagation storms, although they
 253      * can always be engineered deliberately.
 254      *
 255      * @param  msg              is the message to propagate.
 256      * @param  serviceName      is the name of the service.
 257      * @param  serviceParam     is the parameter of the service.
 258      * @param  ttl              The requested TTL for the message.
 259      * @exception  IOException  if an io error occurs
 260      */
 261     public void propagate(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;
 262
 263     /**
 264      * Propagates a message to the specified peers.
 265      *
 266      * @param  destPeerIds      An enumeration of PeerIDs of the peers that are the
 267      * intended recipients of the propagated message.
 268      * @param  msg              The message to propagate.
 269      * @param  serviceName      The name of the service.
 270      * @param  serviceParam     The parameter of the service.
 271      * @param  ttl              The requested TTL for the message.
 272      * @exception  IOException  if an io error occurs
 273      */
 274     public void propagate(Enumeration<? extends ID> destPeerIds, Message msg, String serviceName, String serviceParam, int ttl) throws IOException;
 275
 276     /**
 277      * Propagates a message to members of the peer group reachable via the
 278      * local network. Typically this is accomplished by broadcasting or
 279      * multicasting.
 280      *
 281      * <p/>Only a single HOP at a time is performed. Messages are always
 282      * delivered to the destination handler on arrival. This handler
 283      * is responsible for repropagating further, if deemed appropriate.
 284      *
 285      * <p/>Loop and TTL control are performed automatically.
 286      *
 287      * <p/>Messages can be propagated via this method for the first time or
 288      * can be re-propagated by re-using a message that came in via propagation.
 289      * In the later case, the TTL and loop detection parameters CANNOT be
 290      * re-initialized. If one wants to "re-propagate" a message with a new TTL
 291      * and blank gateways list one must generate a completely new message.
 292      * This limits the risk of accidental propagation storms, although they
 293      * can always be engineered deliberately.
 294      *
 295      * @param  msg              is the message to propagate.
 296      * @param  serviceName      is the name of the service.
 297      * @param  serviceParam     is the parameter of the service.
 298      * @param  ttl              The requested TTL for the message.
 299      * @exception  IOException  if an io error occurs
 300      */
 301     public void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;
 302
 303     /**
 304      * Propagates a message to as many members of the peer group as possible.
 305      *
 306      * <p/>Only a single HOP at a time is performed. Messages are always
 307      * delivered to the destination handler on arrival. This handler
 308      * is responsible for repropagating further, if deemed appropriate.
 309      *
 310      * <p/>Loop and TTL control are performed automatically.
 311      *
 312      * <p/>Messages can be propagated via this method for the first time or
 313      * can be re-propagated by re-using a message that came in via propagation.
 314      * In the later case, the TTL and loop detection parameters CANNOT be
 315      * re-initialized. If one wants to "re-propagate" a message with a new TTL
 316      * and blank gateways list one must generate a completely new message.
 317      * This limits the risk of accidental propagation storms, although they
 318      * can always be engineered deliberately.
 319      *
 320      * @param  msg              is the message to propagate.
 321      * @param  serviceName      is the name of the service
 322      * @param  serviceParam     is the parameter of the service
 323      * @param  ttl              The requested TTL for the message.
 324      * @exception  IOException  if an io error occurs
 325      */
 326     public void propagateInGroup(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;
 327
 328     /**
 329      * Return {@code true} if connected to a rendezvous.
 330      *
 331      * @return {@code true} if connected to a rendezvous otherwise {@code false}.
 332      */
 333     public boolean isConnectedToRendezVous();
 334
 335     /**
 336      * Returns {@code true} if this peer is acting as a rendezvous peer (per the
 337      * implementation definition) within the peer group. {@code false} is
 338      * returned for all other peer roles.
 339      *
 340      * @return {@code true} if this peer is acting as a rendezvous peer (per the
 341      * implementation definition) within the peer group. {@code false} is
 342      * returned for all other peer roles.
 343      */
 344     public boolean isRendezVous();
 345
 346     /**
 347      * Returns the current role of this peer within the peergroup.
 348      *
 349      * @return The current role of this peer within the peergroup.
 350      */
 351     public RendezVousStatus getRendezVousStatus();
 352
 353     /**
 354      *  Enable or disable the automatic switching between an Edge Peer
 355      *  and a Rendezvous Peer.
 356      *
 357      * @param auto {@code true} will activate automatic role switching.
 358      * @return The previous auto start value.
 359      */
 360     public boolean setAutoStart(boolean auto);
 361
 362     /**
 363      *  Enable or disable the automatic switching between an Edge Peer
 364      *  and a Rendezvous Peer.
 365      *
 366      * @param auto {@code true} will activate automatic role switching.
 367      * @param period The interval in milliseconds at which the peer should
 368      * reconsider it's role.
 369      * @return The previous auto start value.
 370      */
 371     public boolean setAutoStart(boolean auto, long period);
 372
 373     /**
 374      * Walk a message through the rendezvous peers of the network: only
 375      * rendezvous peers will receive the message.
 376      *
 377      * <p/>Only a single HOP at a time is performed. Messages are always
 378      * delivered to the destination handler on arrival. This handler
 379      * is responsible for repropagating further, if deemed appropriate.
 380      *
 381      * <p/>Loop and TTL control are performed automatically.
 382      *
 383      * <p/>Messages can be propagated via this method for the first time or
 384      * can be re-propagated by re-using a message that came in via propagation.
 385      * In the later case, the TTL and loop detection parameters CANNOT be
 386      * re-initialized. If one wants to "re-propagate" a message with a new TTL
 387      * and blank gateways list one must generate a completely new message.
 388      * This limits the risk of accidental propagation storms, although they
 389      * can always be engineered deliberately.
 390      *
 391      * <p/><b>Note</b>: The original msg is not modified and may be reused upon return.
 392      *
 393      * @param  msg           is the message to walk.
 394      * @param  serviceName   is the name of the service
 395      * @param  serviceParam  is the parameter of the service
 396      * @param  ttl           is the maximum TTL of the message.
 397      * @throws  IOException  when walking the message is impossible (network failure)
 398      */
 399     public void walk(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;
 400
 401     /**
 402      * <p/>Walk a message through the rendezvous peers of the network: only
 403      * rendezvous peers will receive the message.
 404      *
 405      * <p/>Only a single HOP at a time is performed. Messages are always
 406      * delivered to the destination handler on arrival. This handler
 407      * is responsible for repropagating further, if deemed appropriate.
 408      *
 409      * <p/>Loop and TTL control are performed automatically.
 410      *
 411      * <p/>Messages can be propagated via this method for the first time or
 412      * can be re-propagated by re-using a message that came in via propagation.
 413      * In the later case, the TTL and loop detection parameters CANNOT be
 414      * re-initialized. If one wants to "re-propagate" a message with a new TTL
 415      * and blank gateways list one must generate a completely new message.
 416      * This limits the risk of accidental propagation storms, although they
 417      * can always be engineered deliberately.
 418      *
 419      * <p/><b>Note</b>: The original msg is not modified and may be reused upon return.
 420      *
 421      * @param  destPeerIDs   is a Vector of PeerIDs of the peers which are receiving
 422      * first the walker. Note that each entry in the Vector will create its own
 423      * walker.
 424      * @param  msg           is the message to walk.
 425      * @param  serviceName   is the name of the service
 426      * @param  serviceParam  is the parameter of the service
 427      * @param  ttl           is the maximum TTL of the message.
 428      * @throws  IOException  when walking the message is impossible (network failure)
 429      */
 430     public void walk(Vector<? extends ID> destPeerIDs, Message msg, String serviceName, String serviceParam, int ttl) throws IOException;
 431
 432     /**
 433      * Returns a vector of RdvAdvertisement of the local view of rendezvous peers.
 434      *
 435      * @deprecated Due to design changes, the list of peers may be empty in
 436      * configurations which previously returned a non-empty result. Future
 437      * JXTA versions are likely to use a different API.
 438      *
 439      * @return The local view of RDV peers.
 440      */
 441     @Deprecated
 442     public Vector<RdvAdvertisement> getLocalWalkView();
 443
 444     /**
 445      * Set a new deadline for the rendezvous to be proven alive.
 446      * As a result a lease response must be sought and obtained within the
 447      * specified delay or the rdv is considered disconnected.
 448      *
 449      * <p/>A timeout of 0 or less triggers immediate disconnection.
 450      *
 451      * @param  peer     The peer to be challenged
 452      * @param  timeout  The delay
 453      */
 454     public void challengeRendezVous(ID peer, long timeout);
 455 }