/* *  $Id: RendezVousService.java,v 1.34 2006/05/08 17:56:10 hamada Exp $ * *  Copyright (c) 2001 Sun Microsystems, Inc.  All rights reserved. * *  Redistribution and use in source and binary forms, with or without *  modification, are permitted provided that the following conditions *  are met: * *  1. Redistributions of source code must retain the above copyright *  notice, this list of conditions and the following disclaimer. * *  2. Redistributions in binary form must reproduce the above copyright *  notice, this list of conditions and the following disclaimer in *  the documentation and/or other materials provided with the *  distribution. * *  3. The end-user documentation included with the redistribution, *  if any, must include the following acknowledgment: *  "This product includes software developed by the *  Sun Microsystems, Inc. for Project JXTA." *  Alternately, this acknowledgment may appear in the software itself, *  if and wherever such third-party acknowledgments normally appear. * *  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" *  must not be used to endorse or promote products derived from this *  software without prior written permission. For written *  permission, please contact Project JXTA at http://www.jxta.org. * *  5. Products derived from this software may not be called "JXTA", *  nor may "JXTA" appear in their name, without prior written *  permission of Sun. * *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED *  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE *  DISCLAIMED.  IN NO EVENT SHALL SUN MICROSYSTEMS OR *  ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF *  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, *  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT *  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF *  SUCH DAMAGE. * *  ========================================================= * *  This software consists of voluntary contributions made by many *  individuals on behalf of Project JXTA.  For more *  information on Project JXTA, please see *  <http://www.jxta.org/>. * *  This license is based on the BSD license adopted by the Apache Foundation. */package net.jxta.rendezvous;import java.io.IOException;import java.util.Enumeration;import java.util.Vector;import net.jxta.endpoint.EndpointAddress;import net.jxta.endpoint.EndpointListener;import net.jxta.endpoint.Message;import net.jxta.id.ID;import net.jxta.protocol.PeerAdvertisement;import net.jxta.service.Service;/** * The RendezVous Service provides propagation of messages within a JXTA * PeerGroup. * * <p/>While the internal protcol of diffusion is left to the implementation of * the service, the JXTA RendezVous Service defines a subscription mechanism * allowing JXTA peers to receive propagated messages (clients of the service) * or become a repeater of the service (rendezvous peers). * * <p/>The Standard Reference Implementation requires that at least one peer in * a PeerGroup act as a Rendezvous. Rendezvous peers can dynamically join or * leave the PeerGroup over time. * * @see    <a href="http://spec.jxta.org/nonav/v1.0/docbook/JXTAProtocols.html#proto-rvp" target='_blank'>JXTA Protocols Specification : Rendezvous</a> */public interface RendezVousService extends Service {    /**     *  Perform <code>propagate()</code> or <code>walk()</code> using the most     *  appropriate TTL value for the implementation and configuration. The     *  message will almost certainly be sent with a TTL value much less than     *  this value.     */    public final static int DEFAULT_TTL = Integer.MAX_VALUE;    /**     * Add a peer as a new RendezVousService point.     *     * <p/>If/When the RendezVousService accepts the connection, the RendezVous     * service will invoke the RendezVousMonitor.     *     * @param  adv           the advertisement of the RendezVousService peer     * @throws  IOException  When the specified peer is unreachable     */    public void connectToRendezVous(PeerAdvertisement adv) throws IOException;    /**     * Attempt connection to the specified peer as a new RendezVous point.     *     * <p/>If/When the RendezVous accepts the connection, the RendezVous     * service will invoke the RendezVousMonitor.     *     * @param  addr          EndpointAddress of the rendezvous peer     * @throws  IOException  When the specified peer is unreachable     */    public void connectToRendezVous(EndpointAddress addr) throws IOException;    /**     * Disconnect from the specified rendezvous.     *     * @param  peerID  the PeerId of the RendezVous to disconnect from.     */    public void disconnectFromRendezVous(ID peerID);    /**     * Returns an Enumeration of the PeerID all the RendezVous on which this     * Peer is currentely connected.     *     * @return    Enumeration enumeration of RendezVous.     */    public Enumeration getConnectedRendezVous();    /**     * Returns an Enumeration of the PeerID all the RendezVous on which this     * Peer failed to connect to.     *     * @return    Enumeration of the PeerID all the RendezVous on which this     * Peer failed to connect to.     */    public Enumeration getDisconnectedRendezVous();    /**     * Start the local peer as a RendezVous peer.     */    public void startRendezVous();    /**     * Stop the RendezVous function on the local Peer. All connected Peers are     * disconnected.     */    public void stopRendezVous();    /**     * Returns an Enumeration of PeerID of the peers that are currently     * connected.     *     * @return    Enumeration of PeerID of the peers that are currently     * connected.     */    public Enumeration getConnectedPeers();    /**     * Returns a Vector of PeerID of the peers that are currentely     * connected.     *     * @return    Vector of peers connected to that rendezvous     */    public Vector getConnectedPeerIDs();    /**     *  Registers the given listener under the given name to receive messages     *  propagated by the rendezvous service. The given listener will be added     *  only if no other listener is already registered with these names.     *     *  <p/>For historical reasons the messages that will be received are those     *  address to the ServiceName and ServiceParam pair such that this     *  listener's name is equal to their concatenation. For example, if a     *  message is propagated or walked to a service named "Cheese" with a     *  service parameter of "Burger", it will be received by a propagate     *  listener of name "CheeseBurger".     *     * @param  name             The name of the listener.     * @param  listener         An EndpointListener to process the message.     * @return                  true if listener was registered, otherwise false.     * @exception  IOException  if an io error occurs     * @deprecated              The naming convention is contrary to the more recent usage     * of specifying listeners with separate serviceName and serviceParam.     * Prefer {@link #addPropagateListener(String, String, EndpointListener)}.     */    public boolean addPropagateListener(String name, EndpointListener listener) throws IOException;    /**     * 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.     *     * @param  serviceName   The serviceName of the listener.     * @param  serviceParam  The serviceParam of the listener.     * @param  listener      An EndpointListener to process the message.     * @return               true if listener was registered, otherwise false.     */    public boolean addPropagateListener(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.     *     * @param  name      The name of the listener.     * @param  listener  An EndpointListener to process the message.     * @return           the listener removed, null if the listener was not removed.     * @deprecated       The naming convention is contrary to the more recent usage     * of specifying listeners with separate serviceName and serviceParam.     * Prefer {@link #addPropagateListener(String, String, EndpointListener)}.     */    public EndpointListener removePropagateListener(String name, EndpointListener listener);    /**     * Removes a Listener previously added with addPropagateListener.     * If the given listener is not the one currently registered, nothing is removed.     *     * @param  serviceName   The serviceName of the listener.     * @param  serviceParam  The serviceParam of the listener.     * @param  listener      An EndpointListener to process the message.     * @return               the listener removed, <tt>null</tt> if the listener was not registered.     */    public EndpointListener removePropagateListener(String serviceName, String serviceParam, EndpointListener listener);    /**     * Add a listener for RendezVousEvents.     *     * @param  listener  An RendezvousListener to process the event.     */    public void addListener(RendezvousListener listener);    /**     * Removes a Listener previously added with addListener.     *     * @param  listener  the RendezvousListener listener remove     * @return           true if successful     */    public boolean removeListener(RendezvousListener listener);    /**     * Propagates a message to the local network and to as many members of     * the peer group as possible.     *     * <p/>This method sends the message to all peers, rendezvous peers and     * edge peer. This method of propation 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.     *     * <p/>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 appropropriate.     *     * <p/>Loop and TTL control are performed automatically.     *     * <p/>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.