messenger.java

JXTA&#8482 is a set of open, generalized peer-to-peer (P2P) protocols that allow any networked devi

/*
 * Copyright (c) 2004-2007 Sun Microsystems, Inc.  All rights reserved.
 *  
 *  The Sun Project JXTA(TM) Software License
 *  
 *  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 Sun Microsystems, Inc. for JXTA(TM) technology." 
 *     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.
 *  
 *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United 
 *  States and other countries.
 *  
 *  Please see the license information page at :
 *  <http://www.jxta.org/project/www/license.html> for instructions on use of 
 *  the license in source files.
 *  
 *  ====================================================================
 *  
 *  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.
 * <p/>
 * 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 meaningful 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/>
 * <p/>Each valid state is represented by a integer that is a power of 2.
 * <p/>
 * <p/>The (coarse grain) constants: <code>USABLE, RESOLVED, TERMINAL, IDLE, SATURATED</code> represent meaningful partitions of the space of
 * states.
 * <p/>
 * <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/>
 * <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/>
 * <p/>These constants may be combined by bit logic operators to represent more predicates.  {@link #waitState} accepts such values as
 * a parameter.
 * <p/>
 * <p/>Applications should depend on the coarse grain constants, rather than those denoting discrete 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;

    /**
     * Currently 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/>
     * <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.
     * <p/>
     * Messenger has terminated its useful life. State will never change any more.
     */