1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 * 19 */ 20 package org.apache.mina.statemachine; 21 22 import org.apache.mina.statemachine.event.Event; 23 import org.apache.mina.statemachine.transition.Transition; 24 25 /** 26 * Allows for programmatic control of a state machines execution. 27 * <p> 28 * The <code>*Now()</code> family of methods move to a new {@link State} 29 * immediately and let the new {@link State} handle the current {@link Event}. 30 * The <code>*Next()</code> family on the other hand let the new {@link State} 31 * handle the next {@link Event} which is generated which make these method the 32 * programmatic equivalent of using the {@link org.apache.mina.statemachine.annotation.Transition} annotation. 33 * </p> 34 * <p> 35 * Using the <code>breakAndCall*()</code> and <code>breakAndReturn*</code> methods one 36 * can create sub state machines which behave very much like sub routines. 37 * When calling a state the current state (or the specified <code>returnTo</code> 38 * state) will be pushed on a stack. When returning from a state the last pushed 39 * state will be popped from the stack and used as the new state. 40 * </p> 41 * 42 * @author The Apache MINA Project (dev@mina.apache.org) 43 */ 44 public class StateControl { 45 46 /** 47 * Breaks the execution of the current {@link Transition} and tries to 48 * find another {@link Transition} with higher weight or a {@link Transition} 49 * of a parent {@link State} which can handle the current {@link Event}. 50 */ 51 public static void breakAndContinue() { 52 throw new BreakAndContinueException(); 53 } 54 55 /** 56 * Breaks the execution of the current {@link Transition} and lets the 57 * {@link State} with the specified id handle the <strong>current</strong> {@link Event}. 58 * 59 * @param state the id of the {@link State} to go to. 60 */ 61 public static void breakAndGotoNow(String state) { 62 throw new BreakAndGotoException(state, true); 63 } 64 65 /** 66 * Breaks the execution of the current {@link Transition} and lets the 67 * {@link State} with the specified id handle the <strong>next</strong> {@link Event}. 68 * Using this method is the programmatic equivalent of using the 69 * {@link org.apache.mina.statemachine.annotation.Transition} annotation. 70 * 71 * @param state the id of the {@link State} to go to. 72 */ 73 public static void breakAndGotoNext(String state) { 74 throw new BreakAndGotoException(state, false); 75 } 76 77 /** 78 * Breaks the execution of the current {@link Transition} and lets the 79 * {@link State} with the specified id handle the <strong>current</strong> {@link Event}. 80 * Before moving to the new state the current state will be recorded. The 81 * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()} 82 * will return to the current state. 83 * 84 * @param state the id of the {@link State} to call. 85 */ 86 public static void breakAndCallNow(String state) { 87 throw new BreakAndCallException(state, true); 88 } 89 90 /** 91 * Breaks the execution of the current {@link Transition} and lets the 92 * {@link State} with the specified id handle the <strong>next</strong> {@link Event}. 93 * Before moving to the new state the current state will be recorded. The 94 * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()} 95 * will return to the current state. 96 * 97 * @param state the id of the {@link State} to call. 98 */ 99 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 }