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/20 12:01:21 UTC
svn commit: r586695 - in
/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine: ./
annotation/ context/ event/ mina/ transition/
Author: niklas
Date: Sat Oct 20 03:01:17 2007
New Revision: 586695
URL: http://svn.apache.org/viewvc?rev=586695&view=rev
Log:
* More javadoc.
* Added BreakException as new parent of all exceptions thrown by StateControl.
Added:
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java (with props)
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/annotation/Handler.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handlers.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/State.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContext.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContextLookup.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContext.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContextFactory.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/SingletonStateContextLookup.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContext.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextFactory.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextLookup.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/Event.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/EventArgumentsInterceptor.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/Events.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/MinaStateContextLookup.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AbstractTransition.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AmbiguousMethodException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodInvocationException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodTransition.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoSuchMethodException.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoopTransition.java
mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/Transition.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=586695&r1=586694&r2=586695&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 Sat Oct 20 03:01:17 2007
@@ -25,7 +25,7 @@
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
-class BreakAndCallException extends RuntimeException {
+class BreakAndCallException extends BreakException {
private final String stateId;
private final String returnToStateId;
private final boolean now;
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=586695&r1=586694&r2=586695&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 Sat Oct 20 03:01:17 2007
@@ -25,5 +25,5 @@
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
-class BreakAndContinueException extends RuntimeException {
+class BreakAndContinueException extends BreakException {
}
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=586695&r1=586694&r2=586695&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 Sat Oct 20 03:01:17 2007
@@ -25,7 +25,7 @@
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
-class BreakAndGotoException extends RuntimeException {
+class BreakAndGotoException extends BreakException {
private final String stateId;
private final boolean now;
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=586695&r1=586694&r2=586695&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 Sat Oct 20 03:01:17 2007
@@ -25,7 +25,7 @@
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
-class BreakAndReturnException extends RuntimeException {
+class BreakAndReturnException extends BreakException {
private final boolean now;
public BreakAndReturnException(boolean now) {
Added: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java?rev=586695&view=auto
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java (added)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java Sat Oct 20 03:01:17 2007
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.mina.statemachine;
+
+/**
+ * The base exception of the exceptions thrown by the methods in the
+ * {@link StateControl} class. If you use any of the {@link StateControl}
+ * methods to change the execution of a {@link StateMachine} you must make sure
+ * that exceptions of this type aren't caught and swallowed by your code.
+ *
+ * @author The Apache MINA Project (dev@mina.apache.org)
+ * @version $Rev$, $Date$
+ */
+public class BreakException extends RuntimeException {
+ protected BreakException() {
+ }
+}
Propchange: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/BreakException.java
------------------------------------------------------------------------------
svn:keywords = Rev Date Id
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handler.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handler.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handler.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handler.java Sat Oct 20 03:01:17 2007
@@ -24,9 +24,12 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import org.apache.mina.statemachine.StateMachine;
import org.apache.mina.statemachine.event.Event;
/**
+ * Annotation used on methods to indicate that the method handles a specific
+ * kind of event when in a specific state.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -36,11 +39,29 @@
public @interface Handler {
public static final String SELF = "__self__";
+ /**
+ * Specifies the ids of one or more events handled by the annotated method. If
+ * not specified the handler method will be executed for any event.
+ */
String[] on() default Event.WILDCARD_EVENT_ID;
+ /**
+ * The id of the state or states that this handler applies to. Must be
+ * specified.
+ */
String[] in();
+ /**
+ * The id of the state the {@link StateMachine} should move to next after
+ * executing the annotated method. If not specified the {@link StateMachine}
+ * will remain in the same state.
+ */
String next() default SELF;
+ /**
+ * The weight used to order handler annotations which match the same event
+ * in the same state. Handlers with lower weight will be matched first. The
+ * default weight is 0.
+ */
int weight() default 0;
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handlers.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handlers.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handlers.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/Handlers.java Sat Oct 20 03:01:17 2007
@@ -25,6 +25,7 @@
import java.lang.annotation.Target;
/**
+ * Annotation used to annotate a method with several {@link Handler}s.
*
* @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/annotation/State.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/State.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/State.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/annotation/State.java Sat Oct 20 03:01:17 2007
@@ -25,6 +25,9 @@
import java.lang.annotation.Target;
/**
+ * Annotation used to define the states in a state machine. Only applies to
+ * <code>static final String</code> fields. The value of the string will be used
+ * as state id.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -34,5 +37,8 @@
public @interface State {
public static final String ROOT = "__root__";
+ /**
+ * Sets the id of the parent state. The default is no parent.
+ */
String value() default ROOT;
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContext.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContext.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContext.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContext.java Sat Oct 20 03:01:17 2007
@@ -26,7 +26,8 @@
import org.apache.mina.statemachine.State;
/**
- *
+ * Abstract {@link StateContext} which uses a {@link Map} to store the
+ * attributes.
*
* @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/context/AbstractStateContextLookup.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContextLookup.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContextLookup.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/AbstractStateContextLookup.java Sat Oct 20 03:01:17 2007
@@ -20,7 +20,13 @@
package org.apache.mina.statemachine.context;
/**
- *
+ * Abstract {@link StateContextLookup} implementation. The {@link #lookup(Object[])}
+ * method will loop through the event arguments and call the {@link #supports(Class)}
+ * method for each of them. The first argument that this method returns
+ * <code>true</code> for will be passed to the abstract {@link #lookup(Object)}
+ * method which should try to extract a {@link StateContext} from the argument.
+ * If none is found a new {@link StateContext} will be created and stored in the
+ * event argument using the {@link #store(Object, StateContext)} method.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -28,6 +34,12 @@
public abstract class AbstractStateContextLookup implements StateContextLookup {
private final StateContextFactory contextFactory;
+ /**
+ * Creates a new instance which uses the specified {@link StateContextFactory}
+ * to create {@link StateContext} objects.
+ *
+ * @param contextFactory the factory.
+ */
public AbstractStateContextLookup(StateContextFactory contextFactory) {
if (contextFactory == null) {
throw new NullPointerException("contextFactory");
@@ -49,9 +61,33 @@
return null;
}
+ /**
+ * Extracts a {@link StateContext} from the specified event argument which
+ * is an instance of a class {@link #supports(Class)} returns
+ * <code>true</code> for.
+ *
+ * @param eventArg the event argument.
+ * @return the {@link StateContext}.
+ */
protected abstract StateContext lookup(Object eventArg);
+ /**
+ * Stores a new {@link StateContext} in the specified event argument which
+ * is an instance of a class {@link #supports(Class)} returns
+ * <code>true</code> for.
+ *
+ * @param eventArg the event argument.
+ * @param context the {@link StateContext} to be stored.
+ */
protected abstract void store(Object eventArg, StateContext context);
-
+
+ /**
+ * Must return <code>true</code> for any {@link Class} that this
+ * {@link StateContextLookup} can use to store and lookup
+ * {@link StateContext} objects.
+ *
+ * @param c the class.
+ * @return <code>true</code> or <code>false</code>.
+ */
protected abstract boolean supports(Class c);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContext.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContext.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContext.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContext.java Sat Oct 20 03:01:17 2007
@@ -20,7 +20,7 @@
package org.apache.mina.statemachine.context;
/**
- *
+ * Default {@link StateContext} implementation.
*
* @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/context/DefaultStateContextFactory.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContextFactory.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContextFactory.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/DefaultStateContextFactory.java Sat Oct 20 03:01:17 2007
@@ -20,7 +20,8 @@
package org.apache.mina.statemachine.context;
/**
- *
+ * {@link StateContextFactory} which creates {@link DefaultStateContext}
+ * objects.
*
* @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/context/SingletonStateContextLookup.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/SingletonStateContextLookup.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/SingletonStateContextLookup.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/SingletonStateContextLookup.java Sat Oct 20 03:01:17 2007
@@ -29,10 +29,21 @@
public class SingletonStateContextLookup implements StateContextLookup {
private final StateContext context;
+ /**
+ * Creates a new instance which always returns the same
+ * {@link DefaultStateContext} instance.
+ */
public SingletonStateContextLookup() {
context = new DefaultStateContext();
}
+ /**
+ * Creates a new instance which uses the specified {@link StateContextFactory}
+ * to create the single instance.
+ *
+ * @param contextFactory the {@link StateContextFactory} to use to create
+ * the singleton instance.
+ */
public SingletonStateContextLookup(StateContextFactory contextFactory) {
if (contextFactory == null) {
throw new NullPointerException("contextFactory");
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContext.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContext.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContext.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContext.java Sat Oct 20 03:01:17 2007
@@ -20,16 +20,48 @@
package org.apache.mina.statemachine.context;
import org.apache.mina.statemachine.State;
+import org.apache.mina.statemachine.StateMachine;
/**
- *
+ * {@link StateContext} objects are used to store the current {@link State} and
+ * any application specific attributes for a specific client of a
+ * {@link StateMachine}. Since {@link StateMachine}s are singletons and shared
+ * by all clients using the {@link StateMachine} this is where client specific
+ * data needs to be stored.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public interface StateContext {
+ /**
+ * Returns the current {@link State}. This is only meant for internal use.
+ *
+ * @return the current {@link State}.
+ */
State getCurrentState();
+
+ /**
+ * Sets the current {@link State}. This is only meant for internal use.
+ * Don't call it directly!
+ *
+ * @param state the new current {@link State}.
+ */
void setCurrentState(State state);
- Object getAttribute( Object key );
- void setAttribute( Object key, Object value );
+
+ /**
+ * Returns the value of the attribute with the specified key or
+ * <code>null</code>if not found.
+ *
+ * @param key the key.
+ * @return the value or <code>null</code>.
+ */
+ Object getAttribute(Object key);
+
+ /**
+ * Sets the value of the attribute with the specified key.
+ *
+ * @param key the key.
+ * @param value the value.
+ */
+ void setAttribute(Object key, Object value);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextFactory.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextFactory.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextFactory.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextFactory.java Sat Oct 20 03:01:17 2007
@@ -26,5 +26,10 @@
* @version $Rev$, $Date$
*/
public interface StateContextFactory {
+ /**
+ * Creates a new {@link StateContext}.
+ *
+ * @return the newly created {@link StateContext}.
+ */
StateContext create();
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextLookup.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextLookup.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextLookup.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/context/StateContextLookup.java Sat Oct 20 03:01:17 2007
@@ -19,6 +19,8 @@
*/
package org.apache.mina.statemachine.context;
+import org.apache.mina.statemachine.event.Event;
+
/**
* Lookups a {@link StateContext} from a collection of event arguments.
*
@@ -26,5 +28,15 @@
* @version $Rev$, $Date$
*/
public interface StateContextLookup {
+ /**
+ * Searches the arguments from an {@link Event} and returns a
+ * {@link StateContext} if any of the arguments holds one. NOTE! This method
+ * must create a new {@link StateContext} if a compatible object is in
+ * the arguments and the next time that same object is passed to this
+ * method the same {@link StateContext} should be returned.
+ *
+ * @param eventArgs
+ * @return
+ */
StateContext lookup(Object[] eventArgs);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/Event.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/Event.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/Event.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/Event.java Sat Oct 20 03:01:17 2007
@@ -21,10 +21,11 @@
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.mina.statemachine.context.StateContext;
-;
/**
- *
+ * Represents an event which typically corresponds to a method call on a proxy.
+ * An event has an id and zero or more arguments typically corresponding to
+ * the method arguments.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -36,10 +37,23 @@
private final StateContext context;
private final Object[] arguments;
+ /**
+ * Creates a new {@link Event} with the specified id and no arguments.
+ *
+ * @param id the event id.
+ * @param context the {@link StateContext} the event was triggered for.
+ */
public Event(Object id, StateContext context) {
this(id, context, new Object[0]);
}
+ /**
+ * Creates a new {@link Event} with the specified id and arguments.
+ *
+ * @param id the event id.
+ * @param context the {@link StateContext} the event was triggered for.
+ * @param arguments the event arguments.
+ */
public Event(Object id, StateContext context, Object[] arguments) {
if (id == null) {
throw new NullPointerException("id");
@@ -55,14 +69,30 @@
this.arguments = arguments;
}
+ /**
+ * Returns the {@link StateContext} this {@link Event} was triggered for.
+ *
+ * @return the {@link StateContext}.
+ */
public StateContext getContext() {
return context;
}
+ /**
+ * Returns the id of this {@link Event}.
+ *
+ * @return the id.
+ */
public Object getId() {
return id;
}
+ /**
+ * Returns the arguments of this {@link Event}.
+ *
+ * @return the arguments. Returns an empty array if this {@link Event} has
+ * no arguments.
+ */
public Object[] getArguments() {
return arguments;
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/EventArgumentsInterceptor.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/EventArgumentsInterceptor.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/EventArgumentsInterceptor.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/event/EventArgumentsInterceptor.java Sat Oct 20 03:01:17 2007
@@ -19,14 +19,25 @@
*/
package org.apache.mina.statemachine.event;
+import org.apache.mina.statemachine.StateMachine;
+
/**
- *
+ * Intercepts the {@link Event} arguments before the {@link Event} is passed
+ * to the {@link StateMachine} and allows for the arguments to be modified.
+ * This is for advanced uses only.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public interface EventArgumentsInterceptor {
+ /**
+ * Modifies the specified array of event arguments.
+ *
+ * @param arguments the original arguments.
+ * @return the new arguments. Should return the original array if no
+ * modification is needed.
+ */
Object[] modify(Object[] arguments);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/Events.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/Events.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/Events.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/Events.java Sat Oct 20 03:01:17 2007
@@ -20,9 +20,11 @@
package org.apache.mina.statemachine.mina;
import org.apache.mina.common.IoHandler;
+import org.apache.mina.statemachine.annotation.Handler;
/**
- * Defines all possible MINA {@link IoHandler} events.
+ * Defines all possible MINA {@link IoHandler} events for use in {@link Handler}
+ * annotations.
*
* @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/mina/MinaStateContextLookup.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/MinaStateContextLookup.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/MinaStateContextLookup.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/mina/MinaStateContextLookup.java Sat Oct 20 03:01:17 2007
@@ -24,21 +24,37 @@
import org.apache.mina.statemachine.context.DefaultStateContextFactory;
import org.apache.mina.statemachine.context.StateContext;
import org.apache.mina.statemachine.context.StateContextFactory;
+import org.apache.mina.statemachine.context.StateContextLookup;
/**
- *
+ * MINA specific {@link StateContextLookup} which uses an {@link IoSession}
+ * attribute to store the {@link StateContextLookup}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public class MinaStateContextLookup extends AbstractStateContextLookup {
+ /**
+ * The name of the {@link IoSession} attribute used to store the
+ * {@link StateContext} object.
+ */
public static final String STATE_CONTEXT =
MinaStateContextLookup.class.getName() + ".stateContext";
+ /**
+ * Creates a new instance using a {@link DefaultStateContextFactory} to
+ * create {@link StateContext} objects for new {@link IoSession}s.
+ */
public MinaStateContextLookup() {
this(new DefaultStateContextFactory());
}
-
+
+ /**
+ * Creates a new instance using the specified {@link StateContextFactory} to
+ * create {@link StateContext} objects for new {@link IoSession}s.
+ *
+ * @param contextFactory the {@link StateContextFactory}.
+ */
public MinaStateContextLookup(StateContextFactory contextFactory) {
super(contextFactory);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AbstractTransition.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AbstractTransition.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AbstractTransition.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AbstractTransition.java Sat Oct 20 03:01:17 2007
@@ -23,10 +23,14 @@
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.mina.statemachine.State;
+import org.apache.mina.statemachine.StateMachine;
import org.apache.mina.statemachine.event.Event;
/**
- *
+ * Abstract {@link Transition} implementation. Takes care of matching the
+ * current {@link Event}'s id against the id of the {@link Event} this
+ * {@link Transition} handles. To handle any {@link Event} the id should be set
+ * to {@link Event#WILDCARD_EVENT_ID}.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -36,19 +40,28 @@
private final State nextState;
+ /**
+ * Creates a new instance which will loopback to the same {@link State}
+ * for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ */
public AbstractTransition(Object eventId) {
this(eventId, null);
}
+ /**
+ * Creates a new instance with the specified {@link State} as next state
+ * and for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param nextState the next {@link State}.
+ */
public AbstractTransition(Object eventId, State nextState) {
this.eventId = eventId;
this.nextState = nextState;
}
- public Object getEventId() {
- return eventId;
- }
-
public State getNextState() {
return nextState;
}
@@ -61,6 +74,16 @@
return doExecute(event);
}
+ /**
+ * Executes this {@link Transition}. This method doesn't have to check
+ * if the {@link Event}'s id matches because {@link #execute(Event)} has
+ * already made sure that that is the case.
+ *
+ * @param event the current {@link Event}.
+ * @return <code>true</code> if the {@link Transition} has been executed
+ * successfully and the {@link StateMachine} should move to the
+ * next {@link State}. <code>false</code> otherwise.
+ */
protected abstract boolean doExecute(Event event);
public boolean equals(Object o) {
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AmbiguousMethodException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AmbiguousMethodException.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AmbiguousMethodException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/AmbiguousMethodException.java Sat Oct 20 03:01:17 2007
@@ -20,13 +20,19 @@
package org.apache.mina.statemachine.transition;
/**
- *
+ * Thrown by the constructors in {@link MethodTransition} if there are several
+ * methods with the specifed name in the target object's class.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public class AmbiguousMethodException extends RuntimeException {
+ /**
+ * Creates a new instance using the specified method name as message.
+ *
+ * @param methodName the name of the method.
+ */
public AmbiguousMethodException(String methodName) {
super(methodName);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodInvocationException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodInvocationException.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodInvocationException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodInvocationException.java Sat Oct 20 03:01:17 2007
@@ -22,13 +22,21 @@
import java.lang.reflect.Method;
/**
- *
+ * Thrown by {@link MethodTransition} if the target method couldn't be invoked
+ * or threw an exception.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public class MethodInvocationException extends RuntimeException {
+ /**
+ * Creates a new instance for the specified {@link Method} and
+ * {@link Throwable}.
+ *
+ * @param method the {@link Method}.
+ * @param cause the reason.
+ */
public MethodInvocationException(Method method, Throwable cause) {
super("Invoking method: " + method, cause);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodTransition.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodTransition.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodTransition.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/MethodTransition.java Sat Oct 20 03:01:17 2007
@@ -27,13 +27,33 @@
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.mina.statemachine.State;
+import org.apache.mina.statemachine.StateMachine;
+import org.apache.mina.statemachine.StateMachineFactory;
+import org.apache.mina.statemachine.annotation.Handler;
import org.apache.mina.statemachine.context.StateContext;
import org.apache.mina.statemachine.event.Event;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- *
+ * {@link Transition} which invokes a {@link Method}. The {@link Method} will
+ * only be invoked if its argument types actually matches a subset of the
+ * {@link Event}'s argument types. The argument types are matched in order so
+ * you must make sure the order of the method's arguments corresponds to the
+ * order of the event's arguments.
+ *<p>
+ * If the first method argument type matches
+ * {@link Event} the current {@link Event} will be bound to that argument. In
+ * the same manner the second argument (or first if the method isn't interested
+ * in the current {@link Event}) can have the {@link StateContext} type and will
+ * in that case be bound to the current {@link StateContext}.
+ * </p>
+ * <p>
+ * Normally you wouldn't create instances of this class directly but rather use the
+ * {@link Handler} annotation to define the methods which should be used as
+ * transitions in your state machine and then let {@link StateMachineFactory} create a
+ * {@link StateMachine} for you.
+ * </p>
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
@@ -45,28 +65,95 @@
private final Method method;
private final Object target;
+ /**
+ * Creates a new instance with the specified {@link State} as next state
+ * and for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param nextState the next {@link State}.
+ * @param method the target method.
+ * @param target the target object.
+ */
public MethodTransition(Object eventId, State nextState, Method method, Object target) {
super(eventId, nextState);
this.method = method;
this.target = target;
}
+ /**
+ * Creates a new instance which will loopback to the same {@link State}
+ * for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param method the target method.
+ * @param target the target object.
+ */
public MethodTransition(Object eventId, Method method, Object target) {
this(eventId, null, method, target);
}
+ /**
+ * Creates a new instance with the specified {@link State} as next state
+ * and for the specified {@link Event} id. The target {@link Method} will
+ * be the method in the specified target object with the same name as the
+ * specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param nextState the next {@link State}.
+ * @param target the target object.
+ * @throws NoSuchMethodException if no method could be found with a name
+ * equal to the {@link Event} id.
+ * @throws AmbiguousMethodException if more than one method was found with
+ * a name equal to the {@link Event} id.
+ */
public MethodTransition(Object eventId, State nextState, Object target) {
this(eventId, nextState, eventId.toString(), target);
}
+ /**
+ * Creates a new instance which will loopback to the same {@link State}
+ * for the specified {@link Event} id. The target {@link Method} will
+ * be the method in the specified target object with the same name as the
+ * specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param target the target object.
+ * @throws NoSuchMethodException if no method could be found with a name
+ * equal to the {@link Event} id.
+ * @throws AmbiguousMethodException if more than one method was found with
+ * a name equal to the {@link Event} id.
+ */
public MethodTransition(Object eventId, Object target) {
this(eventId, eventId.toString(), target);
}
+ /**
+ * Creates a new instance which will loopback to the same {@link State}
+ * for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param methodName the name of the target {@link Method}.
+ * @param target the target object.
+ * @throws NoSuchMethodException if the method could not be found.
+ * @throws AmbiguousMethodException if there are more than one method with
+ * the specified name.
+ */
public MethodTransition(Object eventId, String methodName, Object target) {
this(eventId, null, methodName, target);
}
+ /**
+ * Creates a new instance with the specified {@link State} as next state
+ * and for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param nextState the next {@link State}.
+ * @param methodName the name of the target {@link Method}.
+ * @param target the target object.
+ * @throws NoSuchMethodException if the method could not be found.
+ * @throws AmbiguousMethodException if there are more than one method with
+ * the specified name.
+ */
public MethodTransition(Object eventId, State nextState, String methodName, Object target) {
super(eventId, nextState);
@@ -90,10 +177,20 @@
this.method = result;
}
+ /**
+ * Returns the target {@link Method}.
+ *
+ * @return the method.
+ */
public Method getMethod() {
return method;
}
+ /**
+ * Returns the target object.
+ *
+ * @return the target object.
+ */
public Object getTarget() {
return target;
}
@@ -168,10 +265,9 @@
private void invokeMethod(Object[] arguments) {
try {
- if( log.isDebugEnabled() )
- {
- log.debug( "Executing method " + method + " with arguments "
- + Arrays.asList( arguments ));
+ if (log.isDebugEnabled()) {
+ log.debug("Executing method " + method
+ + " with arguments " + Arrays.asList(arguments));
}
method.invoke(target, arguments);
} catch (InvocationTargetException ite) {
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoSuchMethodException.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoSuchMethodException.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoSuchMethodException.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoSuchMethodException.java Sat Oct 20 03:01:17 2007
@@ -20,13 +20,20 @@
package org.apache.mina.statemachine.transition;
/**
- *
+ * {@link RuntimeException} equivalent of {@link java.lang.NoSuchMethodException}.
+ * Thrown by the constructors in {@link MethodTransition} if no method by
+ * the specifed name can be found.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public class NoSuchMethodException extends RuntimeException {
+ /**
+ * Creates a new instance using the specified method name as message.
+ *
+ * @param methodName the name of the method.
+ */
public NoSuchMethodException(String methodName) {
super(methodName);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoopTransition.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoopTransition.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoopTransition.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/NoopTransition.java Sat Oct 20 03:01:17 2007
@@ -30,10 +30,23 @@
*/
public class NoopTransition extends AbstractTransition {
+ /**
+ * Creates a new instance which will loopback to the same {@link State}
+ * for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ */
public NoopTransition(Object eventId) {
super(eventId);
}
+ /**
+ * Creates a new instance with the specified {@link State} as next state
+ * and for the specified {@link Event} id.
+ *
+ * @param eventId the {@link Event} id.
+ * @param nextState the next {@link State}.
+ */
public NoopTransition(Object eventId, State nextState) {
super(eventId, nextState);
}
Modified: mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/Transition.java
URL: http://svn.apache.org/viewvc/mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/Transition.java?rev=586695&r1=586694&r2=586695&view=diff
==============================================================================
--- mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/Transition.java (original)
+++ mina/sandbox/niklas/mina-sm/src/main/java/org/apache/mina/statemachine/transition/Transition.java Sat Oct 20 03:01:17 2007
@@ -20,16 +20,36 @@
package org.apache.mina.statemachine.transition;
import org.apache.mina.statemachine.State;
+import org.apache.mina.statemachine.StateMachine;
import org.apache.mina.statemachine.event.Event;
/**
- *
+ * The interface implemented by classes which need to react on transitions
+ * between states.
*
* @author The Apache MINA Project (dev@mina.apache.org)
* @version $Rev$, $Date$
*/
public interface Transition {
+ /**
+ * Executes this {@link Transition}. It is the responsibility of this
+ * {@link Transition} to determine whether it actually applies for the
+ * specified {@link Event}. If this {@link Transition} doesn't apply
+ * nothing should be executed and <code>false</code> must be returned.
+ *
+ * @param event the current {@link Event}.
+ * @return <code>true</code> if the {@link Transition} was executed,
+ * <code>false</code> otherwise.
+ */
boolean execute(Event event);
- Object getEventId();
+
+ /**
+ * Returns the {@link State} which the {@link StateMachine} should move to
+ * if this {@link Transition} is taken and {@link #execute(Event)} returns
+ * <code>true</code>.
+ *
+ * @return the next {@link State} or <code>null</code> if this
+ * {@link Transition} is a loopback {@link Transition}.
+ */
State getNextState();
}