View Javadoc

    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 <a href="http://mina.apache.org">Apache MINA Project</a>
    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 }