rendezvousservice.java

jxta_src_2.41b jxta 2.41b 最新版源码 from www.jxta.org

/*
 *  $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.