messenger.java

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

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