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 * @version $Rev: 592122 $, $Date: 2007-11-05 20:10:32 +0100 (lun, 05 nov 2007) $
44 */
45 public class StateControl {
46
47 /**
48 * Breaks the execution of the current {@link Transition} and tries to
49 * find another {@link Transition} with higher weight or a {@link Transition}
50 * of a parent {@link State} which can handle the current {@link Event}.
51 */
52 public static void breakAndContinue() {
53 throw new BreakAndContinueException();
54 }
55
56 /**
57 * Breaks the execution of the current {@link Transition} and lets the
58 * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
59 *
60 * @param state the id of the {@link State} to go to.
61 */
62 public static void breakAndGotoNow(String state) {
63 throw new BreakAndGotoException(state, true);
64 }
65
66 /**
67 * Breaks the execution of the current {@link Transition} and lets the
68 * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
69 * Using this method is the programmatic equivalent of using the
70 * {@link org.apache.mina.statemachine.annotation.Transition} annotation.
71 *
72 * @param state the id of the {@link State} to go to.
73 */
74 public static void breakAndGotoNext(String state) {
75 throw new BreakAndGotoException(state, false);
76 }
77
78 /**
79 * Breaks the execution of the current {@link Transition} and lets the
80 * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
81 * Before moving to the new state the current state will be recorded. The
82 * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
83 * will return to the current state.
84 *
85 * @param state the id of the {@link State} to call.
86 */
87 public static void breakAndCallNow(String state) {
88 throw new BreakAndCallException(state, true);
89 }
90
91 /**
92 * Breaks the execution of the current {@link Transition} and lets the
93 * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
94 * Before moving to the new state the current state will be recorded. The
95 * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
96 * will return to the current state.
97 *
98 * @param state the id of the {@link State} to call.
99 */
100 public static void breakAndCallNext(String state) {
101 throw new BreakAndCallException(state, false);
102 }
103
104 /**
105 * Breaks the execution of the current {@link Transition} and lets the
106 * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
107 * Before moving to the new state the current state will be recorded. The
108 * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
109 * will return to the specified <code>returnTo</code> state.
110 *
111 * @param state the id of the {@link State} to call.
112 * @param returnTo the id of the {@link State} to return to.
113 */
114 public static void breakAndCallNow(String state, String returnTo) {
115 throw new BreakAndCallException(state, returnTo, true);
116 }
117
118 /**
119 * Breaks the execution of the current {@link Transition} and lets the
120 * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
121 * Before moving to the new state the current state will be recorded. The
122 * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
123 * will return to the specified <code>returnTo</code> state.
124 *
125 * @param state the id of the {@link State} to call.
126 * @param returnTo the id of the {@link State} to return to.
127 */
128 public static void breakAndCallNext(String state, String returnTo) {
129 throw new BreakAndCallException(state, returnTo, false);
130 }
131
132 /**
133 * Breaks the execution of the current {@link Transition} and lets the
134 * last recorded {@link State} handle the <strong>current</strong> {@link Event}.
135 */
136 public static void breakAndReturnNow() {
137 throw new BreakAndReturnException(true);
138 }
139
140 /**
141 * Breaks the execution of the current {@link Transition} and lets the
142 * last recorded {@link State} handle the <strong>next</strong> {@link Event}.
143 */
144 public static void breakAndReturnNext() {
145 throw new BreakAndReturnException(false);
146 }
147 }