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}