You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by ni...@apache.org on 2007/10/18 22:05:08 UTC
svn commit: r586108 -
/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/
Author: niklas
Date: Thu Oct 18 13:05:07 2007
New Revision: 586108
URL: http://svn.apache.org/viewvc?rev=586108&view=rev
Log:
Added javadoc.
Modified:
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndCallException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndContinueException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndGotoException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndReturnException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/NoSuchStateException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/State.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateControl.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachine.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineCreationException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineFactory.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineProxyFactory.java
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndCallException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndCallException.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndCallException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndCallException.java Thu Oct 18 13:05:07 2007
@@ -20,6 +20,7 @@
package org.apache.mina.statemachine;
/**
+ * Exception used internally by {@link StateControl}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndContinueException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndContinueException.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndContinueException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndContinueException.java Thu Oct 18 13:05:07 2007
@@ -20,6 +20,7 @@
package org.apache.mina.statemachine;
/**
+ * Exception used internally by {@link StateControl}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndGotoException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndGotoException.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndGotoException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndGotoException.java Thu Oct 18 13:05:07 2007
@@ -20,6 +20,7 @@
package org.apache.mina.statemachine;
/**
+ * Exception used internally by {@link StateControl}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndReturnException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndReturnException.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndReturnException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakAndReturnException.java Thu Oct 18 13:05:07 2007
@@ -20,6 +20,7 @@
package org.apache.mina.statemachine;
/**
+ * Exception used internally by {@link StateControl}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/NoSuchStateException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/NoSuchStateException.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/NoSuchStateException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/NoSuchStateException.java Thu Oct 18 13:05:07 2007
@@ -20,14 +20,21 @@
package org.apache.mina.statemachine;
/**
+ * Exception thrown by {@link StateMachine} when a transition in the state
+ * machine references a state which doesn't exist.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public class NoSuchStateException extends RuntimeException {
+ /**
+ * Creates a new instance.
+ *
+ * @param stateId the id of the state which could not be found.
+ */
public NoSuchStateException(String stateId) {
- super(stateId);
+ super("Could not find the state with id: " + stateId);
}
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/State.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/State.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/State.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/State.java Thu Oct 18 13:05:07 2007
@@ -26,9 +26,23 @@
import org.apache.commons.lang.builder.EqualsBuilder;
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;
+import org.apache.mina.statemachine.event.Event;
import org.apache.mina.statemachine.transition.Transition;
/**
+ * Represents a state in a {@link StateMachine}. Normally you wouldn't create
+ * instances of this class directly but rather use the
+ * {@link org.apache.mina.statemachine.annotation.State} annotation to define
+ * your states and then let {@link StateMachineFactory} create a
+ * {@link StateMachine} for you.
+ * <p>
+ * {@link State}s inherits {@link Transition}s from
+ * their parent. A {@link State} can override any of the parents
+ * {@link Transition}s. When an {@link Event} is processed the {@link Transition}s
+ * of the current {@link State} will be searched for a {@link Transition} which
+ * can handle the event. If none is found the {@link State}'s parent will be
+ * searched and so on.
+ * </p>
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -39,23 +53,51 @@
private List<TransitionHolder> transitionHolders = new ArrayList<TransitionHolder>();
private List<Transition> transitions = Collections.emptyList();
+ /**
+ * Creates a new {@link State} with the specified id.
+ *
+ * @param id the unique id of this {@link State}.
+ */
public State(String id) {
this(id, null);
}
+ /**
+ * Creates a new {@link State} with the specified id and parent.
+ *
+ * @param id the unique id of this {@link State}.
+ * @param parent the parent {@link State}.
+ */
public State(String id, State parent) {
this.id = id;
this.parent = parent;
}
+ /**
+ * Returns the id of this {@link State}.
+ *
+ * @return the id.
+ */
public String getId() {
return id;
}
+ /**
+ * Returns the parent {@link State}.
+ *
+ * @return the parent or <code>null</code> if this {@link State} has no
+ * parent.
+ */
public State getParent() {
return parent;
}
+ /**
+ * Returns an unmodifiable {@link List} of {@link Transition}s going out
+ * from this {@link State}.
+ *
+ * @return the {@link Transition}s.
+ */
public List<Transition> getTransitions() {
return Collections.unmodifiableList(transitions);
}
@@ -67,10 +109,27 @@
}
}
+ /**
+ * Adds an outgoing {@link Transition} to this {@link State} with weight 0.
+ *
+ * @param transition the {@link Transition} to add.
+ * @return this {@link State}.
+ * @see #addTransition(Transition, int)
+ */
public State addTransition(Transition transition) {
return addTransition(transition, 0);
}
+ /**
+ * Adds an outgoing {@link Transition} to this {@link State} with the
+ * specified weight. The higher the weight the less important a
+ * {@link Transition} is. If two {@link Transition}s match the same
+ * {@link Event} the {@link Transition} with the lower weight will
+ * be executed.
+ *
+ * @param transition the {@link Transition} to add.
+ * @return this {@link State}.
+ */
public State addTransition(Transition transition, int weight) {
if (transition == null) {
throw new NullPointerException("transition");
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateControl.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateControl.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateControl.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateControl.java Thu Oct 18 13:05:07 2007
@@ -19,45 +19,129 @@
*/
package org.apache.mina.statemachine;
+import org.apache.mina.statemachine.annotation.Handler;
+import org.apache.mina.statemachine.event.Event;
+import org.apache.mina.statemachine.transition.Transition;
+
/**
+ * Allows for programmatic control of a state machines execution.
+ * <p>
+ * The <code>*Now()</code> family of methods move to a new {@link State}
+ * immediately and let the new {@link State} handle the current {@link Event}.
+ * The <code>*Next()</code> family on the other hand let the new {@link State}
+ * handle the next {@link Event} which is generated which make these method the
+ * programmatic equivalent of using the {@link Handler} annotation.
+ * </p>
+ * <p>
+ * Using the <code>breakAndCall*()</code> and <code>breakAndReturn*</code> methods one
+ * can create sub state machines which behave very much like sub routines.
+ * When calling a state the current state (or the specified <code>returnTo</code>
+ * state) will be pushed on a stack. When returning from a state the last pushed
+ * state will be popped from the stack and used as the new state.
+ * </p>
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public class StateControl {
+ /**
+ * Breaks the execution of the current {@link Transition} and tries to
+ * find another {@link Transition} with higher weight or a {@link Transition}
+ * of a parent {@link State} which can handle the current {@link Event}.
+ */
public static void breakAndContinue() {
throw new BreakAndContinueException();
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
+ *
+ * @param state the id of the {@link State} to go to.
+ */
public static void breakAndGotoNow(String state) {
throw new BreakAndGotoException(state, true);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
+ * Using this method is the programmatic equivalent of using the
+ * {@link Handler} annotation.
+ *
+ * @param state the id of the {@link State} to go to.
+ */
public static void breakAndGotoNext(String state) {
throw new BreakAndGotoException(state, false);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
+ * Before moving to the new state the current state will be recorded. The
+ * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
+ * will return to the current state.
+ *
+ * @param state the id of the {@link State} to call.
+ */
public static void breakAndCallNow(String state) {
throw new BreakAndCallException(state, true);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
+ * Before moving to the new state the current state will be recorded. The
+ * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
+ * will return to the current state.
+ *
+ * @param state the id of the {@link State} to call.
+ */
public static void breakAndCallNext(String state) {
throw new BreakAndCallException(state, false);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * {@link State} with the specified id handle the <strong>current</strong> {@link Event}.
+ * Before moving to the new state the current state will be recorded. The
+ * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
+ * will return to the specified <code>returnTo</code> state.
+ *
+ * @param state the id of the {@link State} to call.
+ * @param returnTo the id of the {@link State} to return to.
+ */
public static void breakAndCallNow(String state, String returnTo) {
throw new BreakAndCallException(state, returnTo, true);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * {@link State} with the specified id handle the <strong>next</strong> {@link Event}.
+ * Before moving to the new state the current state will be recorded. The
+ * next call to {@link #breakAndReturnNow()} or {@link #breakAndReturnNext()}
+ * will return to the specified <code>returnTo</code> state.
+ *
+ * @param state the id of the {@link State} to call.
+ * @param returnTo the id of the {@link State} to return to.
+ */
public static void breakAndCallNext(String state, String returnTo) {
throw new BreakAndCallException(state, returnTo, false);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * last recorded {@link State} handle the <strong>current</strong> {@link Event}.
+ */
public static void breakAndReturnNow() {
throw new BreakAndReturnException(true);
}
+ /**
+ * Breaks the execution of the current {@link Transition} and lets the
+ * last recorded {@link State} handle the <strong>next</strong> {@link Event}.
+ */
public static void breakAndReturnNext() {
throw new BreakAndReturnException(false);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachine.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachine.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachine.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachine.java Thu Oct 18 13:05:07 2007
@@ -34,6 +34,12 @@
import org.slf4j.LoggerFactory;
/**
+ * Represents a complete state machine. Contains a collection of {@link State}
+ * objects connected by {@link Transition}s. Normally you wouldn't create
+ * instances of this class directly but rather use the
+ * {@link org.apache.mina.statemachine.annotation.State} annotation to define
+ * your states and then let {@link StateMachineFactory} create a
+ * {@link StateMachine} for you.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -56,6 +62,13 @@
}
};
+ /**
+ * Creates a new instance using the specified {@link State}s and start
+ * state.
+ *
+ * @param states the {@link State}s.
+ * @param startStateId the id of the start {@link State}.
+ */
public StateMachine(State[] states, String startStateId) {
this.states = new HashMap<String, State>();
for (State s : states) {
@@ -64,11 +77,25 @@
this.startState = getState(startStateId);
}
+ /**
+ * Creates a new instance using the specified {@link State}s and start
+ * state.
+ *
+ * @param states the {@link State}s.
+ * @param startStateId the id of the start {@link State}.
+ */
public StateMachine(Collection<State> states, String startStateId) {
this(states.toArray(new State[0]), startStateId);
}
- public State getState(String id) {
+ /**
+ * Returns the {@link State} with the specified id.
+ *
+ * @param id the id of the {@link State} to return.
+ * @return the {@link State}
+ * @throws NoSuchStateException if no matching {@link State} could be found.
+ */
+ public State getState(String id) throws NoSuchStateException {
State state = states.get(id);
if (state == null) {
throw new NoSuchStateException(id);
@@ -76,10 +103,26 @@
return state;
}
+ /**
+ * Returns an unmodifiable {@link Collection} of all {@link State}s used by
+ * this {@link StateMachine}.
+ *
+ * @return the {@link State}s.
+ */
public Collection<State> getStates() {
return Collections.unmodifiableCollection(states.values());
}
+ /**
+ * Processes the specified {@link Event} through this {@link StateMachine}.
+ * Normally you wouldn't call this directly but rather use
+ * {@link StateMachineProxyFactory} to create a proxy for an interface of
+ * your choice. Any method calls on the proxy will be translated into
+ * {@link Event} objects and then fed to the {@link StateMachine} by the
+ * proxy using this method.
+ *
+ * @param event the {@link Event} to be handled.
+ */
public void handle(Event event) {
StateContext context = event.getContext();
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineCreationException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineCreationException.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineCreationException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineCreationException.java Thu Oct 18 13:05:07 2007
@@ -20,6 +20,8 @@
package org.apache.mina.statemachine;
/**
+ * Exception thrown by {@link StateMachineFactory} when a {@link StateMachine}
+ * could not be constructed for some reason.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -28,32 +30,23 @@
public class StateMachineCreationException extends RuntimeException {
/**
+ * Creates a new instance.
*
- */
- public StateMachineCreationException() {
- super();
- }
-
- /**
- * @param message
+ * @param message the message.
*/
public StateMachineCreationException(String message) {
super(message);
}
/**
- * @param message
- * @param cause
+ /**
+ * Creates a new instance.
+ *
+ * @param message the message.
+ * @param cause the cause.
*/
public StateMachineCreationException(String message, Throwable cause) {
super(message, cause);
- }
-
- /**
- * @param cause
- */
- public StateMachineCreationException(Throwable cause) {
- super(cause);
}
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineFactory.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineFactory.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineFactory.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineFactory.java Thu Oct 18 13:05:07 2007
@@ -38,6 +38,9 @@
/**
+ * Creates {@link StateMachine}s by reading {@link org.apache.mina.statemachine.annotation.State},
+ * {@link Handler} and {@link Handlers} annotations from one or more arbitrary
+ * objects.
*
*
* @author The Apache MINA Project (dev@mina.apache.org)
@@ -45,18 +48,59 @@
*/
public class StateMachineFactory {
+ private StateMachineFactory() {
+ }
+
+ /**
+ * Creates a new {@link StateMachine} from the specified handler object and
+ * using a start state with id <code>start</code>.
+ *
+ * @param handler the object containing the annotations describing the
+ * state machine.
+ * @return the {@link StateMachine} object.
+ */
public static StateMachine create(Object handler) {
return create(handler, new Object[0]);
}
+ /**
+ * Creates a new {@link StateMachine} from the specified handler object and
+ * using the {@link State} with the specified id as start state.
+ *
+ * @param start the id of the start {@link State} to use.
+ * @param handler the object containing the annotations describing the
+ * state machine.
+ * @return the {@link StateMachine} object.
+ */
public static StateMachine create(String start, Object handler) {
return create(start, handler, new Object[0]);
}
+ /**
+ * Creates a new {@link StateMachine} from the specified handler objects and
+ * using a start state with id <code>start</code>.
+ *
+ * @param handler the first object containing the annotations describing the
+ * state machine.
+ * @param handlers zero or more additional objects containing the
+ * annotations describing the state machine.
+ * @return the {@link StateMachine} object.
+ */
public static StateMachine create(Object handler, Object... handlers) {
return create("start", handler, handlers);
}
+ /**
+ * Creates a new {@link StateMachine} from the specified handler objects and
+ * using the {@link State} with the specified id as start state.
+ *
+ * @param start the id of the start {@link State} to use.
+ * @param handler the first object containing the annotations describing the
+ * state machine.
+ * @param handlers zero or more additional objects containing the
+ * annotations describing the state machine.
+ * @return the {@link StateMachine} object.
+ */
public static StateMachine create(String start, Object handler, Object... handlers) {
Map<String, State> states = new HashMap<String, State>();
List<Object> handlersList = new ArrayList<Object>(1 + handlers.length);
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineProxyFactory.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineProxyFactory.java?rev=586108&r1=586107&r2=586108&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineProxyFactory.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/StateMachineProxyFactory.java Thu Oct 18 13:05:07 2007
@@ -35,7 +35,7 @@
/**
* Used to create proxies which will forward all method calls on them to a
- * state machine.
+ * {@link StateMachine}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$