/* * * $Id: Messenger.java,v 1.17 2006/01/14 00:48:01 bondolo Exp $ * * Copyright (c) 2004 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.endpoint;import net.jxta.peergroup.PeerGroupID;import net.jxta.util.SimpleSelectable;import java.io.IOException;/** * A Messenger is used to send messages to a destination. * * This interface specifies the allowed observable states for a messenger. (fine grain).  This serves to normalize * the state machines of the various messenger implementations and allows for more meaningfull diagnostics. Implementations may * use substates by adding high order bits, but these should never be reported by the public state observation methods. Most * implementations will not use all these states.   *  * <p/>Each valid state is represented by a integer that is a power of 2. * * <p/>The (coarse grain) constants: <code>USABLE, RESOLVED, TERMINAL, IDLE, SATURATED</code> represent meaningfull partitions of the space of * states. * * <p/>The value of each constant is the bitwise <code>OR</code> of the states for which a given predicate is true: usable or not, * confirmed or not, etc.  Therefore the value of predicate <code>p</code> in state <code>s</code> is <code>(s & p)!=0</code>. * * <p/>These particular predicates are chosen so that they have a relevant truth value for all states. Therefore the bitwise negation * of the corresponding constants represents the obvious: <code>~USABLE</code> really lists all states that mean "not USABLE". * * <p/>These constants may be combined by bit logic operators to represent more predicates.  {@link #waitState} accepts such values as * a parameter. * * <p/>Applications should depend on the coarse grain constants, rather than those denoting descreet states. * * @see net.jxta.endpoint.EndpointService * @see net.jxta.util.SimpleSelector * @see net.jxta.endpoint.EndpointAddress * @see net.jxta.endpoint.Message * @see MessengerState **/public interface Messenger extends SimpleSelectable {    /**     * No message was ever submitted for sending. No connection has ever been attempted.     **/    public static final int UNRESOLVED      = 0x1;    /**     * Initial connection is being attempted. No message is pending.     **/    public static final int RESOLVING       = 0x2;    /**     * Currently connected. No message is pending (being sent implies pending).     **/    public static final int CONNECTED       = 0x4;    /**     * Currently not connected. No message is pending.     **/    public static final int DISCONNECTED    = 0x8;    /**     * Initial connection is being attempted. Messages are pending.     **/    public static final int RESOLPENDING    = 0x10;    /**     * Initial connection is being attempted. Messages are pending. New messages may not be submitted at this time.     **/    public static final int RESOLSATURATED  = 0x20;    /**     * Currently connected and sending messages.     **/    public static final int SENDING         = 0x40;    /**     * Currently sending messages.New messages may not be submitted at this time.     **/    public static final int SENDINGSATURATED= 0x80;    /**     * Currenly trying to re-establish connection. Messages are pending.     **/    public static final int RECONNECTING    = 0x100;    /**     * Currently trying to re-establish connection. New messages may not be submitted at this time.     **/    public static final int RECONSATURATED  = 0x200;    /**     * Attempting initial connection. Close has been requested. Messages are pending.     * New messages may no longer be submitted.     **/    public static final int RESOLCLOSING    = 0x400;        /**     * Currently sending messages. Close has been requested. New messages may no longer be submitted.     **/    public static final int CLOSING         = 0x800;    /**     * Trying to re-establish connection. Close has been requested. Messages are pending.     * New messages may no longer be submitted.     **/    public static final int RECONCLOSING    = 0x1000;    /**     * Failed to establish initial connection. Pending messages are being rejected. New messages may no longer be submitted.     **/    public static final int UNRESOLVING     = 0x2000;    /**     * Failed to re-establish connection.  Pending messages are being rejected. New messages may no longer be submitted.     **/    public static final int BREAKING        = 0x4000;    /**     * Breaking established connection for expedite closure. Pending messages are being rejected.     * New messages may no longer be submitted.     **/    public static final int DISCONNECTING   = 0x8000;    /**     * Failed to establish initial connection. New messages may no longer be submitted. State will never change again.     **/    public static final int UNRESOLVABLE    = 0x10000;    /**     * Failed to re-establish connection.  New messages may no longer be submitted. State will never change again.     **/    public static final int BROKEN          = 0x20000;    /**     * Closed as requested. All pending messages could be sent. New messages may no longer be submitted.     * State will never change again.     **/    public static final int CLOSED          = 0x40000;    /**     * The bitwise OR of all valid states.     **/    public static final int ANYSTATE        = 0x7FFFF;    /* Predicates. */    /**     * Composite state.<p/>     *     * Not known to be broken.     * Messenger may be used to send messages. Viability has not been evaluated yet.     * This is the most useful predicate to applications. USABLE means that     * it is reasonable to try and send a message.     **/    public static final int USABLE        = ( UNRESOLVED | RESOLVING | CONNECTED | DISCONNECTED | RESOLPENDING | RESOLSATURATED | SENDING |                                              SENDINGSATURATED | RECONNECTING | RECONSATURATED);    /**     * Composite state.     *     *  <p/><ul>     *      <li>Messenger was once resolved.</p>     *      <li>Messenger was at least once proven viable. Current usability is      *      not asserted. For example a messenger may be found to be in a      *      TERMINAL state, but also be in a RESOLVED state. Thus proving that      *      the destination of the messenger is sometimes valid.</li>     *  </ul>     **/    public static final int RESOLVED     = (CONNECTED | SENDING | SENDINGSATURATED | CLOSING | CLOSED | DISCONNECTED | RECONNECTING |                                            RECONSATURATED | RECONCLOSING | BREAKING | DISCONNECTING | BROKEN);    /**     * Composite state.