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