001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.mina.statemachine;
021
022import org.apache.mina.statemachine.event.Event;
023import org.apache.mina.statemachine.transition.Transition;
024
025/**
026 * Allows for programmatic control of a state machines execution.
027 * <p>
028 * The <code>*Now()</code> family of methods move to a new {@link State}
029 * immediately and let the new {@link State} handle the current {@link Event}.
030 * The <code>*Next()</code> family on the other hand let the new {@link State}
031 * handle the next {@link Event} which is generated which make these method the 
032 * programmatic equivalent of using the {@link org.apache.mina.statemachine.annotation.Transition} annotation.
033 * </p>
034 * <p>
035 * Using the <code>breakAndCall*()</code> and <code>breakAndReturn*</code> methods one
036 * can create sub state machines which behave very much like sub routines.
037 * When calling a state the current state (or the specified <code>returnTo</code>
038 * state) will be pushed on a stack. When returning from a state the last pushed
039 * state will be popped from the stack and used as the new state.
040 * </p>
041 *
042 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
043 */
044public class StateControl {
045
046    /**
047     * Breaks the execution of the current {@link Transition} and tries to
048     * find another {@link Transition} with higher weight or a {@link Transition}
049     * of a parent {@link State} which can handle the current {@link Event}.
050     */
051    public static void breakAndContinue() {
052        throw new BreakAndContinueException();
053    }
054
055    /**
056     * Breaks the execution of the current {@link Transition} and lets the
057     * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
058     * 
059     * @param state the id of the {@link State} to go to.
060     */
061    public static void breakAndGotoNow(String state) {
062        throw new BreakAndGotoException(state, true);
063    }
064
065    /**
066     * Breaks the execution of the current {@link Transition} and lets the
067     * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
068     * Using this method is the programmatic equivalent of using the
069     * {@link org.apache.mina.statemachine.annotation.Transition} annotation.
070     * 
071     * @param state the id of the {@link State} to go to.
072     */
073    public static void breakAndGotoNext(String state) {
074        throw new BreakAndGotoException(state, false);
075    }
076
077    /**
078     * Breaks the execution of the current {@link Transition} and lets the
079     * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
080     * Before moving to the new state the current state will be recorded. The
081     * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
082     * will return to the current state.
083     * 
084     * @param state the id of the {@link State} to call.
085     */
086    public static void breakAndCallNow(String state) {
087        throw new BreakAndCallException(state, true);
088    }
089
090    /**
091     * Breaks the execution of the current {@link Transition} and lets the
092     * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
093     * Before moving to the new state the current state will be recorded. The
094     * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
095     * will return to the current state.
096     * 
097     * @param state the id of the {@link State} to call.
098     */
099    public static void breakAndCallNext(String state) {
100        throw new BreakAndCallException(state, false);
101    }
102
103    /**
104     * Breaks the execution of the current {@link Transition} and lets the
105     * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
106     * Before moving to the new state the current state will be recorded. The
107     * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
108     * will return to the specified <code>returnTo</code> state.
109     * 
110     * @param state the id of the {@link State} to call.
111     * @param returnTo the id of the {@link State} to return to.
112     */
113    public static void breakAndCallNow(String state, String returnTo) {
114        throw new BreakAndCallException(state, returnTo, true);
115    }
116
117    /**
118     * Breaks the execution of the current {@link Transition} and lets the
119     * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
120     * Before moving to the new state the current state will be recorded. The
121     * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
122     * will return to the specified <code>returnTo</code> state.
123     * 
124     * @param state the id of the {@link State} to call.
125     * @param returnTo the id of the {@link State} to return to.
126     */
127    public static void breakAndCallNext(String state, String returnTo) {
128        throw new BreakAndCallException(state, returnTo, false);
129    }
130
131    /**
132     * Breaks the execution of the current {@link Transition} and lets the
133     * last recorded {@link State} handle the <strong>current</strong> {@link Event}.
134     */
135    public static void breakAndReturnNow() {
136        throw new BreakAndReturnException(true);
137    }
138
139    /**
140     * Breaks the execution of the current {@link Transition} and lets the
141     * last recorded {@link State} handle the <strong>next</strong> {@link Event}.
142     */
143    public static void breakAndReturnNext() {
144        throw new BreakAndReturnException(false);
145    }
146}