endpointservice.java

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

/*
 * 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.
 *
 * $Id: EndpointService.java,v 1.28 2005/11/21 19:50:58 bondolo Exp $
 */

package net.jxta.endpoint;

import java.util.Iterator;

import java.io.IOException;

import net.jxta.peergroup.PeerGroup;
import net.jxta.service.Service;

/**
 * The EndpointService provides the API for sending and receiving messages
 * between peers. In general, applications and services use the
 * {@link net.jxta.pipe.PipeService} rather than using this API directly.
 *
 **/
public interface EndpointService extends Service, EndpointListener {
    
    public static final int LowPrecedence = 0;
    public static final int MediumPrecedence = 1;
    public static final int HighPrecedence = 2;

    /**
     * Returns the group to which this EndpointService is attached.
     *
     * @return PeerGroup the group.
     */
    public PeerGroup getGroup();
    
    /**
     * Returns a messenger to the specified destination. The canonical messenger is shared between all channels which destination
     * contains the same protocol name and protocol address, in all groups that have access to the same transport. The
     * ChannelMessenger returned is configured to send messages to the specified service name and service param when these are not
     * specified at the time of sending.<p/>
     *
     * The channel will also ensure delivery to this EndpointService's group on arrival. The channel is not shared with any other
     * module. That is, each endpoint service interface object (as returned by {@link
     * net.jxta.peergroup.PeerGroup#getEndpointService()}) will return a different channel messenger for the same
     * destination. However, there is no guarantee that two invocations of the same endpoint service interface object for the same
     * destination will return different channel objects. Notably, if the result of a previous invocation is still strongly
     * referenced and in a {@link Messenger#USABLE} state, then that is what this method will return.<p/>
     *
     * This method returns immediately. The messenger is not necessarily resolved (the required underlying connection established,
     * for example), and it might never resolve at all.  Changes in the state of a messenger may monitored with {@link
     * Messenger#getState} and {@link Messenger#waitState}. One may monitor multiple {@link Messenger messengers} (and {@link
     * Message Messages}) at a time by using a {@link net.jxta.util.SimpleSelector}.  One may also arrange to have a listener invoked when
     * resolution is complete by using {@link ListenerAdaptor}.<p/>
     *
     * The hint is interpreted by the transport. The only transport known to consider hints is the endpoint router, and the hint
     * is a route.  As a result, if addr is in the form: jxta://uniqueID, then hint may be a RouteAdvertisement.  If that route is
     * valid the router will add it to it's cache of route and may then use it to succesfully create a messenger to the given
     * destination.  There is no garantee at this time that the route will end up being the one specified, nor that this route
     * will be used only for this messenger (likely the opposite), nor that it will remain in use in the future, nor that it will
     * be used at all. However, if there is no other route, and if the specified route is valid, it will be used rather than
     * seeking an alternative.<p/>
     *
     * @see net.jxta.endpoint.EndpointAddress
     * @see net.jxta.endpoint.ChannelMessenger
     *
     * @param addr The complete destination address.
     * @param hint A hint to be supplied to whichever transport ends-up making the the real messenger. May be null, when no
     * hint applies.
     * @return The messenger, not necessarily functional, nor resolved. May be null if the address
     * is not handled by any of the available transports.
     **/
    public Messenger getMessengerImmediate( EndpointAddress addr, Object hint );

    /**
     * Behaves like {@link #getMessengerImmediate(EndpointAddress, Object)}, except that the invoker is blocked until the
     * messenger resolves or fails to do so.
     *
     * @param addr the destination address.
     * @param hint A hint if there is one. Null, otherwise.
     * @return The messenger. null is returned if the destination address is not reachable.
     **/
    public Messenger getMessenger(EndpointAddress addr, Object hint);
    
    /**
     * Creates and maps a canonical messenger to the specified destination.<p/>
     *
     * Behaves like {@link #getMessengerImmediate(EndpointAddress, Object)} except that it returns a canonical messenger.
     *
     * The messenger is said to be canonical, because there is only one such live object for any given destination address. The
     * term live, here means that the messenger is not in any of the {@link Messenger#TERMINAL} states as defined by {@link
     * MessengerState}. Therefore, for a given destination there may be any number of messengers in a {@link
     * Messenger#TERMINAL} state, but at most one in any other state. As long as such an object exists, all calls to
     * <code>getCanonicalMessenger</code> for the same address return this very object.<p/>
     * 
     * When first created, a canonical messenger is usually in the {@link Messenger#UNRESOLVED} state. It becomes resolved by
     * obtaining an actual transport messenger to the destination upon the first attempt at using it or when first forced to
     * attempt resolution. Should resolution fail at that point, it becomes {@link Messenger#UNRESOLVABLE}. Otherwise, subsequent,
     * failures are repaired automatically by obtaining a new transport messenger when needed. If a failure cannot be repaired,
     * the messenger becomes {@link Messenger#BROKEN}.<p/>
     *
     * <code>getCanonicalMessenger</code> is a recursive function. Exploration of the parent endpoint is done automatically.<p/>
     *
     * <b>Note 1:</b> This method is the most fundamental messenger instantiation method. It creates a different messenger for
     * each variant of destination address passed to the constructor. In general invokers should use plain addresses; stripped of
     * any service-specific destination.<p/>
     *
     * <b>Note 2:</b> The messengers that this method returns, are not generally meant to be used directly. They provide a single
     * queue for all invokers, and do not perform group redirection and only support only a subset of the <code>sendMessage</code>
     * methods.  One must get a properly configured channel in order to send messages.<p/>
     *
     * If one of the other <code>getMessenger</code> methods fits the application needs, it should be preferred.
     *
     * @param addr The destination address. It is recommended, though not mandatory that the address be
     * stripped of its service name and service param elements.
     * @param hint An object, of a type specific to the protocol of the address, that may be provide additional
     * information to the transport in establishing the connection. Typically but not necessarily, this is a route advertisement.
     * If the transport cannot use the hint, or if it is null, it will be ignored.
     * @return A Canonical messenger that obtains transport messengers to the specified address, from LOCAL transports. Returns
     * null if no no local transport handles this type address.
     *
     * @see Messenger
     **/
    public Messenger getCanonicalMessenger( EndpointAddress addr, Object hint );


    /**
     *  Removes the specified listener.
     *
     *  @param listener The listener that would have been called.
     *  @param priority Priority set from which to remove this listener.
     *  @return true if the listener was removed, otherwise false.
     **/
    public boolean removeMessengerEventListener( MessengerEventListener listener, int priority );

    /**
     *  Adds the specified listener for all messenger creation.
     *
     *  @param listener The listener that will be called.
     *  @param priority Order of precedence requested (from 0 to 2). 2 has highest precedence Listeners are called in decreasing
     *  order of precedence. Listeners with equal precedence are called in unpredictible order relative to each other. There
     *  cannot be more than one listener object for a given precedence. Redundant calls have no effect.
     *  @return true if the listener was added, otherwise false.
     **/
    public boolean addMessengerEventListener( MessengerEventListener listener, int priority );
    
    /**
     * Propagates the given message through all the endpoint protocols that are available to this endpoint. Some or all of these