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: */
020: package org.apache.mina.statemachine;
021:
022: import org.apache.mina.statemachine.event.Event;
023: import 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 The Apache MINA Project (dev@mina.apache.org)
043: * @version $Rev: 592122 $, $Date: 2007-11-05 12:10:32 -0700 (Mon, 05 Nov 2007) $
044: */
045: public class StateControl {
046:
047: /**
048: * Breaks the execution of the current {@link Transition} and tries to
049: * find another {@link Transition} with higher weight or a {@link Transition}
050: * of a parent {@link State} which can handle the current {@link Event}.
051: */
052: public static void breakAndContinue() {
053: throw new BreakAndContinueException();
054: }
055:
056: /**
057: * Breaks the execution of the current {@link Transition} and lets the
058: * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
059: *
060: * @param state the id of the {@link State} to go to.
061: */
062: public static void breakAndGotoNow(String state) {
063: throw new BreakAndGotoException(state, true);
064: }
065:
066: /**
067: * Breaks the execution of the current {@link Transition} and lets the
068: * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
069: * Using this method is the programmatic equivalent of using the
070: * {@link org.apache.mina.statemachine.annotation.Transition} annotation.
071: *
072: * @param state the id of the {@link State} to go to.
073: */
074: public static void breakAndGotoNext(String state) {
075: throw new BreakAndGotoException(state, false);
076: }
077:
078: /**
079: * Breaks the execution of the current {@link Transition} and lets the
080: * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
081: * Before moving to the new state the current state will be recorded. The
082: * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
083: * will return to the current state.
084: *
085: * @param state the id of the {@link State} to call.
086: */
087: public static void breakAndCallNow(String state) {
088: throw new BreakAndCallException(state, true);
089: }
090:
091: /**
092: * Breaks the execution of the current {@link Transition} and lets the
093: * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
094: * Before moving to the new state the current state will be recorded. The
095: * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
096: * will return to the current state.
097: *
098: * @param state the id of the {@link State} to call.
099: */
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: }
|