messengerstate.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;

/**
 * The complete standard messenger life cycle state machine that all messengers
 * must obey. Compliant messengers can be built by implementing and using this
 * class as an engine to orchestrate discrete operations.
 * <p/>
 * In order to use this class, one must implement the various abstract Action
 * methods, so that they trigger the required operations.
 * <p/>
 * Synchronization has to be externally provided and usually needs to extend
 * around sections wider than just the invocation of this class' methods. For
 * example, if the user of this class maintains a queue, the state of the queue
 * must be kept consistent with the invocation of {@link #msgsEvent},
 * {@link #saturatedEvent}, and {@link #idleEvent}, which all denote different
 * states of that queue. It is suggested to use the instance of this class as
 * the synchronization object.
 */
public abstract class MessengerState {

    // All the transition map setup is rather terse because java tends to make 
    // it extremely verbose. We do not want to end up with 1000 lines of code 
    // for what amounts to initializing a table.

    // Below is a method reference. It permits putting "what to do" in a field.
    // The {@code doIt()} method is given the target object because we want our
    // entire transition table to be a static singleton. Otherwise it would cost
    // too much initializing each instance of this class.

    private interface Action {
        public void doIt(MessengerState messengerState);
    }

    // Action method "pointers".
    // The transition table is static. Otherwise it would cost too much initializing each instance of this class.

    private final static Action Connect = new Action() {
        public void doIt(MessengerState messengerState) {
            messengerState.connectAction();
        }
    };
    private final static Action Closein = new Action() {
        public void doIt(MessengerState s) {
            s.closeInputAction();
        }
    };
    private final static Action Start = new Action() {
        public void doIt(MessengerState s) {
            s.startAction();
        }
    };
    private final static Action Closeout = new Action() {
        public void doIt(MessengerState messengerState) {
            messengerState.closeOutputAction();
        }
    };
    private final static Action Failall = new Action() {
        public void doIt(MessengerState messengerState) {
            messengerState.failAllAction();
        }
    };
    private final static Action Closeio = new Action() {
        public void doIt(MessengerState s) {
            s.closeInputAction();
            s.closeOutputAction();
        }
    };
    private final static Action Closefail = new Action() {
        public void doIt(MessengerState messengerState) {
            messengerState.closeInputAction();
            messengerState.failAllAction();
        }
    };
    private final static Action Nop = new Action() {
        public void doIt(MessengerState messengerState) {
        }
    };

    /**
     * The transition each event causes when in that state.
     */
    private static class State {
        private final int number;

        private State stResolve;
        private Action acResolve;

        private State stMsgs;
        private Action acMsgs;

        private State stSaturated;
        private Action acSaturated;

        private State stClose;
        private Action acClose;

        private State stShutdown;
        private Action acShutdown;

        private State stUp;
        private Action acUp;

        private State stDown;
        private Action acDown;

        private State stIdle;
        private Action acIdle;

        State(int stateNum) {
            number = stateNum;
        }

        void init(Object[] data) {
            stResolve = (State) data[0];
            acResolve = (Action) data[1];
            stMsgs = (State) data[2];
            acMsgs = (Action) data[3];
            stSaturated = (State) data[4];
            acSaturated = (Action) data[5];
            stClose = (State) data[6];
            acClose = (Action) data[7];
            stShutdown = (State) data[8];
            acShutdown = (Action) data[9];
            stUp = (State) data[10];
            acUp = (Action) data[11];
            stDown = (State) data[12];
            acDown = (Action) data[13];
            stIdle = (State) data[14];
            acIdle = (Action) data[15];
        }
    }


    // All the states. (We put them together in a class essentially to simplify initialization).
    private static class TransitionMap {

        private final static State Unresolved = new State(Messenger.UNRESOLVED);
        private final static State ResPending = new State(Messenger.RESOLPENDING);
        private final static State Resolving = new State(Messenger.RESOLVING);
        private final static State ResolSat = new State(Messenger.RESOLSATURATED);
        private final static State Connected = new State(Messenger.CONNECTED);
        private final static State Disconned = new State(Messenger.DISCONNECTED);
        private final static State Reconning = new State(Messenger.RECONNECTING);
        private final static State ReconSat = new State(Messenger.RECONSATURATED);
        private final static State Sending = new State(Messenger.SENDING);
        private final static State SendingSat = new State(Messenger.SENDINGSATURATED);
        private final static State ResClosing = new State(Messenger.RESOLCLOSING);
        private final static State ReconClosing = new State(Messenger.RECONCLOSING);
        private final static State Closing = new State(Messenger.CLOSING);
        private final static State Disconning = new State(Messenger.DISCONNECTING);
        private final static State Unresable = new State(Messenger.UNRESOLVABLE);
        private final static State Closed = new State(Messenger.CLOSED);
        private final static State Broken = new State(Messenger.BROKEN);

        // The states need to exist before init, because they refer to each other.
        // We overwrite them in-place with the complete data.

        private final static Object[][] INIT_TRANSITION_MAP = {

                /* STATE resolve, msgs, saturated, close, shutdown, up, down, idle */

                /* UNRESOLVED      */
                {Resolving, Connect, ResPending, Connect, ResolSat, Connect, Closed, Closein, Broken, Closein, Connected, Nop, Unresolved, Nop, Unresolved, Nop},

                /* RESOLPENDING    */
                {ResPending, Nop, ResPending, Nop, ResolSat, Nop, ResClosing, Closein, Broken, Closefail, Sending, Start, Unresable, Closefail, Resolving, Nop},