DPML Notify

[niclas AT netcompartner.com]

Author: niclas
Date: Thu Feb  3 08:34:34 2005
New Revision: 1708

Modified:
   
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
   
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionListener.java
   
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionRule.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleComponent.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleImpl.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/SimpleState.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateComponent.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateMachineImpl.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionComponent.java
   
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionImpl.java
   
development/laboratory/planet/components/fsm/demo/trafficlight/src/main/net/dpml/fsm/trafficlight/Timer.java
Log:
Added some javadocs, and made checkstyle 100% happy with the formatting.

Modified: 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
 (original)
+++ 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
 Thu Feb  3 08:34:34 2005
@@ -30,6 +30,9 @@
 public class TransitionEvent
     implements Serializable
 {
+    /** Hashcode constant. */
+    private static final int HASHCODE_MULTIPLIER = 29;
+
     /** SerialVersionUID for this class. */
     static final long serialVersionUID = 1L;
 
@@ -161,9 +164,9 @@
     {
         int result;
         result = m_transition.hashCode();
-        result = 29 * result + m_stateMachine.hashCode();
-        result = 29 * result + m_source.hashCode();
-        result = 29 * result + m_transitionDate.hashCode();
+        result = HASHCODE_MULTIPLIER * result + m_stateMachine.hashCode();
+        result = HASHCODE_MULTIPLIER * result + m_source.hashCode();
+        result = HASHCODE_MULTIPLIER * result + m_transitionDate.hashCode();
         return result;
     }
 

Modified: 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionListener.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionListener.java
      (original)
+++ 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionListener.java
      Thu Feb  3 08:34:34 2005
@@ -33,6 +33,7 @@
     /** Event fired when a transition occur from one state to another.
      * It is intended that the functionality tied to the state machine
      * is implemented thorugh this interface.
+     * @param event the TransitionEvent being sent.
      */
     void transition( TransitionEvent event );
 }

Modified: 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionRule.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionRule.java
  (original)
+++ 
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionRule.java
  Thu Feb  3 08:34:34 2005
@@ -45,5 +45,12 @@
      */
     boolean isTransition( String commandString );
 
+    /** Return the priority of the TransitionRule.
+     * Transition rules are evaluated in priority order, with the lowest 
number
+     * first, and therefor the first <code>isTransition()</code> that returns
+     * <code>true</code> will take precedence of which Transition that will
+     * occur.
+     * @return the priority number of the TransitionRule.
+     */
     int getPriority();
 }

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleComponent.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleComponent.java
    (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleComponent.java
    Thu Feb  3 08:34:34 2005
@@ -35,6 +35,9 @@
 public class CommandRuleComponent extends CommandRuleImpl
     implements TransitionRule
 {
+    /** Default priority if not provided. */
+    private static final int DEFAULT_PRIORITY = 100;
+
     /** Constructor for Metro component.
      * The expected parameters in the params argument are;
      * <ul>
@@ -60,7 +63,7 @@
     {
         super(
             params.getParameter( "command", null ),
-            params.getParameterAsInteger( "priority", 100 ),
+            params.getParameterAsInteger( "priority", DEFAULT_PRIORITY ),
             params.getParameterAsBoolean( "ignore-case", false )
         );
     }

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleImpl.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleImpl.java
 (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/CommandRuleImpl.java
 Thu Feb  3 08:34:34 2005
@@ -33,14 +33,25 @@
 public class CommandRuleImpl
     implements TransitionRule
 {
+    /** The command of this CommandRule. */
     private String m_command;
+
+    /** The priority for this Rule. */
     private int m_priority;
+
+    /** If rule is ignoring the case or not. */
     private boolean m_ignoreCase;
 
+    /** The constructor of a CommandRuleImpl.
+     * @param command the command of the rule.
+     * @param priority the priority of this rule.
+     * @param ignoreCase true if the commands given later, should ignore the 
case.
+     * @exception NullArgumentException if the command is null or an empty 
String.
+     */
     public CommandRuleImpl( String command, int priority, boolean ignoreCase 
)
         throws NullArgumentException
     {
-        if( command == null )
+        if( command == null || command.length() == 0 )
         {
             throw new NullArgumentException( "command" );
         }
@@ -66,16 +77,25 @@
         return m_command.equals( commandString );
     }
 
+    /** Return the command of the rule.
+     * @return this rule's command.
+     */
     public String getCommand()
     {
         return m_command;
     }
 
+    /** Return the priority of the rule.
+     * @return the priority of this rule.
+     */
     public int getPriority()
     {
         return m_priority;
     }
 
+    /** Return true if the case of the commands are ignored.
+     * @return true if case case is ignored, false if the command is 
case-sensitive.
+     */
     public boolean isIgnoringCase()
     {
         return m_ignoreCase;
@@ -111,8 +131,6 @@
      * @return a negative integer, zero, or a positive integer as this 
object is less than, equal
      *         to, or greater than the specified object.
      *
-     * @throws ClassCastException if the specified object's type prevents it 
from being compared to
-     *                            this Object.
      */
     public int compareTo( Object o )
     {
@@ -121,50 +139,100 @@
             TransitionRule rule = (TransitionRule) o;
             int p = rule.getPriority();
             if( p == m_priority )
+            {
                 return 0;
+            }
             if( p > m_priority )
+            {
                 return -1;
+            }
             else
+            {
                 return 1;
+            }
         }
         return -1;
     }
 
+    /** Override for toString().
+     * The string return is "CommandRule[" + m_command + ", " + m_priority + 
c + "]"
+     * where c == ", ignore-case" if isIgnoringCase() returns true, 
otherwise an empty
+     * string.
+     * @return a string representing this rule.
+     */
     public String toString()
     {
         String c = "";
-        if( m_ignoreCase )
+        if( isIgnoringCase() )
+        {
             c = ", ignore-case";
+        }
         String s = "CommandRule[" + m_command + ", " + m_priority + c + "]";
         return s;
     }
 
+    /* Satisfy checkstyle. */
+    /** Hash constant */
+    private static final int HASH_CONSTANT1 = 16312786;
+    /** Hash constant */
+    private static final int HASH_CONSTANT2 = 271234;
+    /** Hash constant */
+    private static final int HASH_CONSTANT3 = 31;
+    /** Hash constant */
+    private static final int HASH_CONSTANT4 = 61732179;
+    /** Hash constant */
+    private static final int HASH_CONSTANT5 = 19;
+    /** Hash constant */
+    private static final int HASH_CONSTANT6 = 812398721;
+
+    /** Hashcode of the rule.
+     * @return the hashCode.
+     */
     public int hashCode()
     {
         int cmdHash = m_command.hashCode();
-        int hash = cmdHash + ( ( cmdHash & 31 ) * 16312786 );
-        hash = hash + 61732179 * m_priority + 271234;
+        int hash = cmdHash + ( ( cmdHash & HASH_CONSTANT3 ) * HASH_CONSTANT1 
);
+        hash = hash + HASH_CONSTANT4 * m_priority + HASH_CONSTANT2;
         if( m_ignoreCase )
-            hash = hash * 19;
+        {
+            hash = hash * HASH_CONSTANT5;
+        }
         else
-            hash = hash + 812398721;
+        {
+            hash = hash + HASH_CONSTANT6;
+        }
         return hash;
     }
-
+    /** Override of equals().
+     * A CommandRuleImple is only equal another instance, if that instance
+     * is also a CommandRuleImpl, and not a subclass, and that the priority,
+     * command string and ignoreCase are identically set.
+     *
+     * @param o the other object to compare with.
+     *
+     * @return true if the objects are the same.
+     */
     public boolean equals( Object o )
     {
         if( o == null )
+        {
             return false;
-        if( ! ( o instanceof CommandRuleImpl ) )
+        }
+        if( !( o.getClass().equals( CommandRuleImpl.class ) ) )
+        {
             return false;
+        }
         CommandRuleImpl other = (CommandRuleImpl) o;
 
         if( m_priority != other.m_priority )
+        {
             return false;
+        }
 
         if( m_ignoreCase ^ other.m_ignoreCase )
+        {
             return false;
-
+        }
         return m_command.equals( other.m_command );
     }
 }

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/SimpleState.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/SimpleState.java
     (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/SimpleState.java
     Thu Feb  3 08:34:34 2005
@@ -18,12 +18,8 @@
 
 package net.dpml.fsm.basic;
 
-import java.util.Locale;
-import java.util.ResourceBundle;
-
 import net.dpml.fsm.AbstractState;
 import net.dpml.fsm.State;
-import net.dpml.fsm.StateMachine;
 
 import net.dpml.lang.NullArgumentException;
 
@@ -51,17 +47,27 @@
 public class SimpleState extends AbstractState
     implements State
 {
+    /** Simple constructor for a simple state.
+     * @param identity the Identity of this simple state.
+     * @exception NullArgumentException if the identity is null or an empty 
string.
+     */
     public SimpleState( String identity )
         throws NullArgumentException
     {
         super( identity );
     }
 
+    /** Callback method for state is entered.
+     * The default implementation doesn't do anything in this method.
+     */
     public void entry()
     {
         // default: No action.
     }
 
+    /** Callback method for state is exited.
+     * The default implementation doesn't do anything in this method.
+     */
     public void exit()
     {
         // default: No action.

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateComponent.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateComponent.java
  (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateComponent.java
  Thu Feb  3 08:34:34 2005
@@ -24,6 +24,8 @@
 import net.dpml.fsm.AbstractState;
 import net.dpml.fsm.State;
 
+import net.dpml.lang.NullArgumentException;
+
 /**
  * This component represents each State internal in the StateMachine.
  * <p/>
@@ -50,23 +52,33 @@
 public class StateComponent extends AbstractState
     implements State
 {
-    /**
+    /** Metro compatible constructor.
      * @metro.entry key="urn:metro:name"
+     * @param ctx the container context for this component.
+     * @exception NullArgumentException if the identity is null or an empty 
string.
+     * @exception ContextException if the container context has not been 
populated
+     *            with the "urn:metro:name" entry.
      */
     public StateComponent( Context ctx )
-        throws ContextException
+        throws ContextException, NullArgumentException
     {
         super( (String) ctx.get( "urn:metro:name" ) );
     }
 
+    /** Callback method for state is entered.
+     * The default implementation doesn't do anything in this method.
+     */
     public void entry()
     {
-        // Default: do nothing
+        // default: No action.
     }
 
+    /** Callback method for state is exited.
+     * The default implementation doesn't do anything in this method.
+     */
     public void exit()
     {
-        // Default: do nothing
+        // default: No action.
     }
 }
 

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateMachineImpl.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateMachineImpl.java
        (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/StateMachineImpl.java
        Thu Feb  3 08:34:34 2005
@@ -39,10 +39,24 @@
 public class StateMachineImpl
     implements StateMachine
 {
+    /** Hashmap containing all the transitions of this StateMachine. */
     private HashMap m_transitions;
+
+    /** Cross index of 'begin' States vs Transitions, for faster lookup.
+     * The key of the map is the State, and the value is the Transition.
+     */
     private WeakHashMap m_crossIndex;
+
+    /** Current State of the Statemachine.
+     * The Statemachine will be in an unknown State until it is
+     * <code>reset()</code>.
+     */
     private State m_currentState;
 
+    /** Constructor for the StateMachine.
+     * The StateMachine requires no configuration, so this constructor is
+     * Metro compatible, as well as can be used for plain Java apps.
+     */
     public StateMachineImpl()
     {
         m_transitions = new HashMap();
@@ -52,12 +66,15 @@
     /**
      * Trigger a change in the StateMachine.
      *
+     * @param source the object instance that calls this method.
      * @param commandString The command string to be evaluated.
      */
     public void trigger( Object source, String commandString )
     {
         if( m_currentState == null )
+        {
             return;
+        }
 
         Transition transition = null;
         synchronized( this )
@@ -84,11 +101,21 @@
         }
     }
 
+    /** Return the current state of the StateMachine.
+     * The current state will remain in an unknown state until the 
StateMachine
+     * has been <code>reset()</code>.
+     * @return the current State of this StateMachine.
+     */
     public State getCurrentState()
     {
         return m_currentState;
     }
 
+    /** Add a Transition to this StateMachine.
+     * Transitions contains the 'begin' and 'end' States, which will make up
+     * the StateMachine.
+     * @param transition the Transition to add to this StateMachine.
+     */
     public void addTransition( Transition transition )
     {
         synchronized( this )
@@ -98,12 +125,17 @@
             State begin = transition.getBeginState();
             Collection bucket = (Collection) m_crossIndex.remove( begin );
             if( bucket == null )
+            {
                 bucket = new TreeSet();
+            }
             bucket.add( transition );
             m_crossIndex.put( begin, bucket );
         }
     }
 
+    /** Add zero, one or many Transitions to this StateMachine.
+     * @param transitions a Collection of Transition instances to be added.
+     */
     public void addTransitions( Collection transitions )
     {
         synchronized( this )
@@ -117,6 +149,9 @@
         }
     }
 
+    /** Remove a Transition from this StateMachine.
+     * @param transition the Transition to remove from this StateMachine.
+     */
     public void removeTransition( Transition transition )
     {
         synchronized( this )
@@ -127,10 +162,15 @@
             Collection bucket = (Collection) m_crossIndex.remove( begin );
             bucket.remove( transition );
             if( bucket.size() > 0 )
+            {
                 m_crossIndex.put( begin, bucket );
+            }
         }
     }
 
+    /** Removes all Transition instances from this StateMachine and sets the
+     * current state into 'unknown'.
+     */
     public void removeAllTransitions()
     {
         synchronized( this )
@@ -142,6 +182,23 @@
         }
     }
 
+    /** Add a TransitionListener to the StateMachine.
+     * <p/>
+     * It is <strong>required</strong> that the implementation can handle any
+     * number of TransitionListeners.
+     * Implementations should probably delegate the management of the
+     * TransitionListeners down to the Transition itself, as to easier allow
+     * for the requirement that a TransitionListener can be register with a
+     * null transitionId argument, followed by a removeTransitionListener
+     * for one or more Transitions that is of no interest, and get the
+     * notifications for the other Transitions.
+     *
+     * @param listener the TransitionListener to be added. More than one
+     *        registration of the same TransitionListener instance *must* be
+     *        allowed.
+     * @param transitionId the Transition of interest, or null if all 
Transitions
+     *        should be notified.
+     */
     public void addTransitionListener( TransitionListener listener, String 
transitionId )
     {
         synchronized( this )
@@ -163,6 +220,15 @@
         }
     }
 
+    /** Remove a TransitionListener from the StateMachine.
+     * If the TransitionListener is registered with a null 
<code>transitionId</code>,
+     * i.e. for all Transitions, this method must ONLY remove the
+     * TransitionListener for the provided transitionId in this method call.
+
+     * @param listener the TransitionListener to remove. If more than one
+     *        registration is found only one of them should be removed.
+     * @param transitionId the Transition that is no longer of interest.
+     */
     public void removeTransitionListener( TransitionListener listener, 
String transitionId )
     {
         synchronized( this )
@@ -184,6 +250,14 @@
         }
     }
 
+    /** Remove a TransitionListener from the StateMachine.
+     * <p/>
+     * The TransitionListener is to be removed completely, and no longer is
+     * interested in any more notifications.
+     *
+     * @param listener the TransitionListener to remove. If more than one
+     *        registration is found only one of them should be removed.
+     */
     public void removeTransitionListener( TransitionListener listener )
     {
         synchronized( this )
@@ -197,12 +271,21 @@
         }
     }
 
+    /** Resets the StateMachine into a known initial State.
+     * Reset is an asynchronous method, and implementations 
<strong>must</strong>
+     * ensure that any on-going Transition is completed, prior to setting the
+     * current State into the provided <code>initialState</code>.
+     *
+     * @param initialState the State to put the StateMachine into.
+     */
     public void reset( State initialState )
     {
         synchronized( this )
         {
             if( m_crossIndex.get( initialState ) == null )
+            {
                 throw new IllegalStateException( initialState + " is not 
part of this StateMachine" );
+            }
             m_currentState = initialState;
             m_currentState.entry();
         }

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionComponent.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionComponent.java
     (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionComponent.java
     Thu Feb  3 08:34:34 2005
@@ -45,19 +45,32 @@
 public class TransitionComponent
     implements Transition
 {
+    /** The 'begin' State of the Transition. */
     private State           m_beginState;
+
+    /** The 'end' State of the Transition. */
     private State           m_endState;
+
+    /** The Id of the Transition. */
     private String          m_identity;
+
+    /** The TransitionRule to trigger the Transition on. */
     private TransitionRule  m_rule;
+
+    /** The TransitionListeners. */
     private ArrayList       m_listeners;
+
+    /** The Logger instance. */
     private Logger          m_logger;
 
     /**
      * @param man    The ServiceManager for this component.
-     * @param params Parameters for this component.
+     * @param ctx    Context for this component.
+     * @param logger A logger instance to send diagnostics to.
+     *
+     * @throws ContextException   if the container provided context is not
+     *         populated with a "urn:metro:name" entry.
      *
-     * @throws ParameterException if a "identity" parameter is not 
specified, which is used as key
-     *                            in ResourceBundle lookups.
      * @throws ServiceException   if the "begin" and "end" StateImpl 
dependencies can not be
      *                            satisfied.
      *
@@ -86,26 +99,49 @@
         m_listeners = new ArrayList();
     }
 
+    /** Returns the TransitionRule for this Transition.
+     * @return the TransitionRule for this Transition.
+     */
     public TransitionRule getTransitionRule()
     {
         return m_rule;
     }
 
+    /** Return the State where the Transition is originating from.
+     * @return the State where the Transition is originating from.
+     */
     public State getBeginState()
     {
         return m_beginState;
     }
 
+    /** Return the State to where the Transition is leading.
+     * @return the State to where the Transition is leading.
+     */
     public State getEndState()
     {
         return m_endState;
     }
 
+    /** Return the Identity of the Transition.
+     * <p/>
+     * The Identity is important to identify the Transition in the running
+     * system, as well as to locate the localized name and description of the
+     * Transition.
+     * @return the Identity of the Transition.
+     */
     public String getIdentity()
     {
         return m_identity;
     }
 
+    /** Return the Name of the Transition in the provided Locale.
+     *
+     * @param locale The java.util.Locale to return the name in.
+     * @param classloader the ClassLoader to use to load the Locale 
resources with.
+     *
+     * @return the human-readable Name of the Transition in the provided 
Locale.
+     */
     public String getName( Locale locale, ClassLoader classloader )
     {
         String name = StateMachine.BUNDLE_NAME;
@@ -113,6 +149,14 @@
         return bundle.getString( m_identity + ".name" );
     }
 
+    /** Return the Description of the Transition in the provided Locale.
+     *
+     * @param locale The java.util.Locale to return the description in.
+     * @param classloader the ClassLoader to use to load the Locale 
resources with.
+     *
+     * @return the human-readable Description of the Transition in the 
provided
+     *         Locale.
+     */
     public String getDescription( Locale locale, ClassLoader classloader )
     {
         String name = StateMachine.BUNDLE_NAME;
@@ -120,6 +164,19 @@
         return bundle.getString( m_identity + ".description" );
     }
 
+    /** Called by the StateMachine to execute the Transition.
+     * <p/>
+     * The implementation should notify the begin and end States of the 
exit()
+     * and entry() respectively, and notify all the TransitionListeners.
+     * The TransitionListeners <strong>must</strong> be notified after both 
the
+     * States has been notified.
+     *
+     * @param source the client object instance that issued the trigger in 
the
+     *        StateMachine, causing the Transition to occur.
+     * @param fsm the StateMachine that this Transition belongs to.
+     *
+     * @return the State that is now the new current state.
+     */
     public State execute( Object source, StateMachine fsm )
     {
         m_beginState.exit();
@@ -136,7 +193,8 @@
             {
                 TransitionListener listener = (TransitionListener) 
list.next();
                 listener.transition( event );
-            } catch( Exception e )
+            }
+            catch( Exception e )
             {
                 m_logger.error( "Exception in TransitionListener.", e );
             }
@@ -144,6 +202,15 @@
         return m_endState;
     }
 
+    /** Add a TransitionListener to the Transition.
+     * <p/>
+     * It is <strong>required</strong> that the implementation can handle any
+     * number of TransitionListeners.
+     *
+     * @param listener the TransitionListener to be added. More than one
+     *        registration of the same TransitionListener instance *must* be
+     *        allowed.
+     */
     public void addTransitionListener( TransitionListener listener )
     {
         synchronized( m_listeners )
@@ -154,6 +221,11 @@
         }
     }
 
+    /** Remove a TransitionListener from the Transition.
+     * @param listener the TransitionListener to remove. If there is more 
than]
+     *        one entry of the TransitionListener register, only remove one 
of
+     *        the instances.
+     */
     public void removeTransitionListener( TransitionListener listener )
     {
         synchronized( m_listeners )
@@ -164,6 +236,13 @@
         }
     }
 
+    /** equals() override.
+     * The equals method returns true if the other object is a Transition
+     * instance, the 'begin' and 'end' States are equals and both the 
Identity
+     * and the TransitionRule are equal as this instance.
+     * @param o the object to compare with.
+     * @return true if the other object is equal to this instance.
+     */
     public boolean equals( Object o )
     {
         if( this == o )
@@ -198,6 +277,9 @@
         return true;
     }
 
+    /** Override for hashCode().
+     * @return the hash value for this instance.
+     */
     public int hashCode()
     {
         int hash;
@@ -208,8 +290,12 @@
         return hash;
     }
 
+    /** Override toString() method.
+     * The returned string will be <code> "Transition[" + getIdentity() + 
"]"</code>.
+     * @return string representation of this class.
+     */
     public String toString()
     {
-        return "Transition[" + m_identity +"]";
+        return "Transition[" + getIdentity() + "]";
     }
 }

Modified: 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionImpl.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionImpl.java
  (original)
+++ 
development/laboratory/planet/components/fsm/basic/src/main/net/dpml/fsm/basic/TransitionImpl.java
  Thu Feb  3 08:34:34 2005
@@ -41,19 +41,32 @@
 public class TransitionImpl
     implements Transition
 {
-    private State m_beginState;
-    private State m_endState;
-    private String m_identity;
-    private TransitionRule m_rule;
-    private ArrayList m_listeners;
-    private Logger    m_logger;
-    /*
+    /** The 'begin' State of the Transition. */
+    private State           m_beginState;
+
+    /** The 'end' State of the Transition. */
+    private State           m_endState;
+
+    /** The Id of the Transition. */
+    private String          m_identity;
+
+    /** The TransitionRule to trigger the Transition on. */
+    private TransitionRule  m_rule;
+
+    /** The TransitionListeners. */
+    private ArrayList       m_listeners;
+
+    /** The Logger instance. */
+    private Logger          m_logger;
+
+    /**
      * Non-Metro constructor.
      *
      * @param beginState The StateImpl from which this Transition starts at.
      * @param endState   The StateImpl to where this Transition leads to.
      * @param identity   The Identity of this Transition.
      * @param rule       The TransitionRule for this transition to activate.
+     * @param logger     A logger instance to send diagnostics to.
      */
     public TransitionImpl( State beginState, State endState, String identity,
             TransitionRule rule, Logger logger )
@@ -78,26 +91,49 @@
         m_listeners = new ArrayList();
     }
 
+    /** Returns the TransitionRule for this Transition.
+     * @return the TransitionRule for this Transition.
+     */
     public TransitionRule getTransitionRule()
     {
         return m_rule;
     }
 
+    /** Return the State where the Transition is originating from.
+     * @return the State where the Transition is originating from.
+     */
     public State getBeginState()
     {
         return m_beginState;
     }
 
+    /** Return the State to where the Transition is leading.
+     * @return the State to where the Transition is leading.
+     */
     public State getEndState()
     {
         return m_endState;
     }
 
+    /** Return the Identity of the Transition.
+     * <p/>
+     * The Identity is important to identify the Transition in the running
+     * system, as well as to locate the localized name and description of the
+     * Transition.
+     * @return the Identity of the Transition.
+     */
     public String getIdentity()
     {
         return m_identity;
     }
 
+    /** Return the Name of the Transition in the provided Locale.
+     *
+     * @param locale The java.util.Locale to return the name in.
+     * @param classloader the ClassLoader to use to load the Locale 
resources with.
+     *
+     * @return the human-readable Name of the Transition in the provided 
Locale.
+     */
     public String getName( Locale locale, ClassLoader classloader )
     {
         String name = StateMachine.BUNDLE_NAME;
@@ -105,6 +141,14 @@
         return bundle.getString( m_identity + ".name" );
     }
 
+    /** Return the Description of the Transition in the provided Locale.
+     *
+     * @param locale The java.util.Locale to return the description in.
+     * @param classloader the ClassLoader to use to load the Locale 
resources with.
+     *
+     * @return the human-readable Description of the Transition in the 
provided
+     *         Locale.
+     */
     public String getDescription( Locale locale, ClassLoader classloader )
     {
         String name = StateMachine.BUNDLE_NAME;
@@ -112,6 +156,19 @@
         return bundle.getString( m_identity + ".description" );
     }
 
+    /** Called by the StateMachine to execute the Transition.
+     * <p/>
+     * The implementation should notify the begin and end States of the 
exit()
+     * and entry() respectively, and notify all the TransitionListeners.
+     * The TransitionListeners <strong>must</strong> be notified after both 
the
+     * States has been notified.
+     *
+     * @param source the client object instance that issued the trigger in 
the
+     *        StateMachine, causing the Transition to occur.
+     * @param fsm the StateMachine that this Transition belongs to.
+     *
+     * @return the State that is now the new current state.
+     */
     public State execute( Object source, StateMachine fsm )
     {
         m_beginState.exit();
@@ -128,7 +185,8 @@
             {
                 TransitionListener listener = (TransitionListener) 
list.next();
                 listener.transition( event );
-            } catch( Exception e )
+            }
+            catch( Exception e )
             {
                 m_logger.error( "Exception in TransitionListener.", e );
             }
@@ -136,6 +194,15 @@
         return m_endState;
     }
 
+    /** Add a TransitionListener to the Transition.
+     * <p/>
+     * It is <strong>required</strong> that the implementation can handle any
+     * number of TransitionListeners.
+     *
+     * @param listener the TransitionListener to be added. More than one
+     *        registration of the same TransitionListener instance *must* be
+     *        allowed.
+     */
     public void addTransitionListener( TransitionListener listener )
     {
         synchronized( m_listeners )
@@ -146,6 +213,11 @@
         }
     }
 
+    /** Remove a TransitionListener from the Transition.
+     * @param listener the TransitionListener to remove. If there is more 
than]
+     *        one entry of the TransitionListener register, only remove one 
of
+     *        the instances.
+     */
     public void removeTransitionListener( TransitionListener listener )
     {
         synchronized( m_listeners )
@@ -156,6 +228,13 @@
         }
     }
 
+    /** equals() override.
+     * The equals method returns true if the other object is a Transition
+     * instance, the 'begin' and 'end' States are equals and both the 
Identity
+     * and the TransitionRule are equal as this instance.
+     * @param o the object to compare with.
+     * @return true if the other object is equal to this instance.
+     */
     public boolean equals( Object o )
     {
         if( this == o )
@@ -190,6 +269,9 @@
         return true;
     }
 
+    /** Override for hashCode().
+     * @return the hash value for this instance.
+     */
     public int hashCode()
     {
         int hash;
@@ -200,8 +282,12 @@
         return hash;
     }
 
+    /** Override toString() method.
+     * The returned string will be <code> "Transition[" + getIdentity() + 
"]"</code>.
+     * @return string representation of this class.
+     */
     public String toString()
     {
-        return "Transition[" + m_identity +"]";
+        return "Transition[" + m_identity + "]";
     }
 }

Modified: 
development/laboratory/planet/components/fsm/demo/trafficlight/src/main/net/dpml/fsm/trafficlight/Timer.java
==============================================================================
--- 
development/laboratory/planet/components/fsm/demo/trafficlight/src/main/net/dpml/fsm/trafficlight/Timer.java
        (original)
+++ 
development/laboratory/planet/components/fsm/demo/trafficlight/src/main/net/dpml/fsm/trafficlight/Timer.java
        Thu Feb  3 08:34:34 2005
@@ -28,6 +28,9 @@
 import net.dpml.fsm.Transition;
 import net.dpml.fsm.TransitionEvent;
 import net.dpml.fsm.TransitionListener;
+
+import net.dpml.parameters.Parameters;
+
 import net.dpml.service.ServiceException;
 import net.dpml.service.ServiceManager;
 
@@ -37,27 +40,60 @@
 public class Timer
     implements Runnable, Startable, TransitionListener
 {
+    /** Default wait time for red light. */
+    private static final int DEFAULT_WAIT_RED = 5000;
+
+    /** Default wait time for yellow light. */
+    private static final int DEFAULT_WAIT_YELLOW = 1000;
+
+    /** Default wait time for green light. */
+    private static final int DEFAULT_WAIT_GREEN = 5000;
+
+    /** The StateMachine that operates this traffic light. */
     private StateMachine    m_stateMachine;
+
+    /** The initial state of this traffic light */
     private State           m_initial;
+
+    /** Wait counter. */
     private int             m_nextWait;
+
+    /** Thread running the StateMachine. */
     private Thread          m_thread;
+
+    /** Thread run flag. */
     private boolean         m_run;
 
+    /** Configuration of how long to wait with red light. */
+    private int            m_redWait;
+
+    /** Configuration of how long to wait with yellow light. */
+    private int            m_yellowWait;
+
+    /** Configuration of how long to wait with green light. */
+    private int            m_greenWait;
+
     /**
      * @param man ServiceManager servicing this Part.
+     * @param params The wait parameters for the traffic light states.
      *
      * @throws ServiceException if any of the required dependencies can not 
be satisfied.
      * @metro.dependency type="net.dpml.fsm.StateMachine" key="fsm"
      * @metro.dependency type="net.dpml.fsm.State" key="initial-state"
      */
-    public Timer( ServiceManager man )
+    public Timer( ServiceManager man, Parameters params )
         throws ServiceException
     {
         System.out.println( "Creating Trafficlight." );
         m_stateMachine = (StateMachine) man.lookup( "fsm" );
         m_initial = (State) man.lookup( "initial-state" );
+        m_redWait = params.getParameterAsInteger( "wait-for-red", 
DEFAULT_WAIT_RED );
+        m_yellowWait = params.getParameterAsInteger( "wait-for-yellow", 
DEFAULT_WAIT_YELLOW );
+        m_greenWait = params.getParameterAsInteger( "wait-for-green", 
DEFAULT_WAIT_GREEN );
     }
 
+    /** Starting the Traffic light.
+     */
     public void start()
     {
         System.out.println( "Starting Trafficlight." );
@@ -65,6 +101,8 @@
         m_thread.start();
     }
 
+    /** Stopping the Traffic Light.
+     */
     public void stop()
     {
         System.out.println( "Stopping Trafficlight." );
@@ -72,12 +110,14 @@
         m_thread.interrupt();
     }
 
+    /** Entry point for running the Thread.
+     */
     public void run()
     {
         m_run = true;
         String command = "next";
         m_stateMachine.reset( m_initial );
-        m_nextWait = 1000;
+        m_nextWait = 0;
         m_stateMachine.addTransitionListener( this, null );
         try
         {
@@ -89,11 +129,17 @@
                     m_stateMachine.trigger( this, command );
                 }
             }
-        } catch( InterruptedException e )
+        }
+        catch( InterruptedException e )
         {
+            System.out.println( "Traffic light interrupted." );
         }
     }
 
+    /** Transition occurred.
+     * Called from the StateMachine to indicate a Transition change.
+     * @param event the TransitionEvent that has occurred.
+     */
     public void transition( TransitionEvent event )
     {
         Transition transition = event.getTransition();
@@ -106,10 +152,16 @@
 
         String id = state.getIdentity();
         if( id.equals( "red" ) )
-            m_nextWait = 5000;
+        {
+            m_nextWait = m_redWait;
+        }
         if( id.equals( "yellow" ) )
-            m_nextWait = 1000;
-        if( id.equals( "red" ) )
-            m_nextWait = 5000;
+        {
+            m_nextWait = m_yellowWait;
+        }
+        if( id.equals( "green" ) )
+        {
+            m_nextWait = m_greenWait;
+        }
     }
 }