DPML Notify

[mcconnell AT dpml.net]

Author: mcconnell AT dpml.net
Date: Mon Apr 18 17:14:44 2005
New Revision: 2310

Modified:
   
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
   
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
   
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
   
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
Log:
javadocing

Modified: 
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
==============================================================================
--- 
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
    (original)
+++ 
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
    Mon Apr 18 17:14:44 2005
@@ -58,6 +58,18 @@
     */
     public AbstractStateManager( Logger logger, ChangeListener listener, 
Object instance )
     {
+        if( null == logger )
+        {
+            throw new NullPointerException( "logger" );
+        }
+        if( null == instance )
+        {
+            throw new NullPointerException( "instance" );
+        }
+        if( null == listener )
+        {
+            throw new NullPointerException( "listener" );
+        }
         m_instance = instance;
         m_listener = listener;
         m_logger = logger;
@@ -77,6 +89,10 @@
     */
     protected Object getHandler( String key ) throws NoSuchHandlerException
     {
+        if( null == key )
+        {
+            throw new NullPointerException( "key" );
+        }
         Object handler = m_handlers.get( key );
         if( null == handler )
         {
@@ -87,6 +103,14 @@
 
     protected void addHandler( String key, Object handler )
     {
+        if( null == key )
+        {
+            throw new NullPointerException( "key" );
+        }
+        if( null == handler )
+        {
+            throw new NullPointerException( "handler" );
+        }
         if( m_handlers.containsKey( key ) )
         {
             throw new DuplicateKeyException( key );
@@ -100,9 +124,16 @@
     }
 
    /**
-    * Initialization of the manager by a controller.  This implementation 
will attempt assign
-    * an initial state declared within the supplied state graph.  If no 
initial state is present
-    * the implementation will return the root state.
+    * Initialization of the manager by a controller.  If the state model
+    * declares a terminal root state this methods does nothing and returns.
+    * If the root state is not terminal the implementation will invoke a 
+    * transiton named "initalize".  If the transition relts in a modified 
+    * state, the implementation will continue to recursivly invoke an 
+    * an initialize operation until either a condition occurs where 
invocation 
+    * of the nearest initization transition will not modify the current 
state.
+    *
+    * @exception Exception if an error is raised by a handler assigned to 
+    *  and invoked initialization transiton
     */
     public synchronized void initialize() throws Exception
     {
@@ -127,9 +158,21 @@
     }
 
    /**
-    * Retun the current state of execution.
+    * Retun the current state. The current state is the function of 
+    * the initialization and subsequent trnaistion actions applied to 
+    * the state model.  The current state determines the enabled 
+    * state chain as the sequence of states from the current state to 
+    * root state.  Any transitions defined in the active state chain 
+    * are candidates for execution.  Transitions logically closer to the
+    * current state override transitions declare higher up in the 
+    * state chain. This method is exposed via the ServiceManager 
+    * interface to the controlling application (possibly the enclossing 
+    * component or the model controller).  State instances returned from 
+    * this method are automatically proxied behind a State invocation
+    * handler thereby ensuring the integrity of the state's state and 
+    * non-disclosure of implemetation features.
     *
-    * @return the state representing the current state of execution
+    * @return the current state
     */
     public synchronized State getState()
     {
@@ -137,7 +180,8 @@
     }
 
    /**
-    * Utility method to return the current state implemetation class.
+    * Internal utility method that returns a non-proxied reference to the 
+    * current state.
     *
     * @return the state representing the current state of execution
     */
@@ -158,10 +202,13 @@
    /**
     * Apply a transition identified by a supplied transition key.  The 
     * implementation will attempt to locate the transition relative to the 
current
-    * state (taking into account the DefaultState search semantics) fro which
+    * state (taking into account the DefaultState search semantics) from 
which
     * a invocation handler is resolve and invoked.  If the transition is 
successful
-    * the target tranaistion state declared by the transtion will be 
assigned as the 
+    * the target transition state declared by the transtion will be assigned 
as the 
     * current current state and all listeners will be notified of a state 
change.
+    * If the transition resolved from the supplied key references a target 
state 
+    * that is the same as the current state the transition will not be 
invoked and
+    * the method will return false.
     * 
     * @param key the transition key
     * @return TRUE if the transition was executed
@@ -196,6 +243,26 @@
         }
     }
    
+   /**
+    * Internal utility method that handles the resolution of a handler based 
on 
+    * the object assigned to the DefaultTransition handler attribute.  If 
the 
+    * handler is an instance of URI, the following schemes will be evaluated:
+    *
+    * <ol>
+    *   <li>part:[key] - invocation of the handle method on the component's 
part
+    *       referenced by the scheme specific part of the supplied uri</li>
+    *   <li>handler:[key] - invocation of the handle method on a class 
identified by 
+    *       the scheme specific part of the uri</li>
+    *   <li>method:[key] - invocation of the handle method against the 
component
+    *       instance</li>
+    * </ol>
+    * 
+    * @param handler the object describing the handler
+    * @param state the current state
+    * @param target the target of the transition 
+    * @param logger the assigned logging channel
+    * @excetion Exception of an invocation or handler error occurs
+    */
     private void execute( Object handler, State state, State target, Logger 
logger ) throws Exception
     {
          if( handler instanceof URI )
@@ -247,8 +314,26 @@
                  throw new IllegalArgumentException( error );
              }
          }
+         else
+         {
+             final String error = 
+               "Handler class not supported."
+               + "\nClass: " + handler.getClass().getName()
+               + "\nComponent Class: " + m_instance.getClass().getName();
+             throw new IllegalArgumentException( error );
+         }
     }
 
+   /**
+    * Internal utility to populate method arguments using the current state, 
target state
+    * assigned logging channel, and the active component instance.
+    *
+    * @param parameters the array of method parameter arguments
+    * @param state the current state
+    * @param target the transition target state
+    * @param logger the assinged logging channel
+    * @return the populated object array
+    */
     private Object[] resolveArguments( Class[] parameters, State state, 
State target, Logger logger )
     {
         boolean firstStateAssigned = false;
@@ -329,10 +414,10 @@
         }
         try
         {
-            apply( "terminate" );
-            if( false == getCurrentState().equals( state ) )
+            boolean flag = true;
+            while( flag )
             {
-                terminate();
+                flag = apply( "terminate" );
             }
         }
         catch( NoSuchTransitionException e )
@@ -354,6 +439,15 @@
         return m_logger;
     }
 
+   /**
+    * Utility to locate athe first public method with the supplied name in 
the 
+    * supplied class.
+    * @param c the class to introspect
+    * @param operation the method name
+    * @return the first method found  
+    * @exception IllegalArgumentException if the class does not delcare the 
+    *    the named method
+    */
     private Method locateMethod( Class c, String operation )
     {
         Method[] methods = c.getMethods();

Modified: 
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
==============================================================================
--- 
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
    (original)
+++ 
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
    Mon Apr 18 17:14:44 2005
@@ -67,14 +67,23 @@
     }
 
    /**
-    * Internal constructor for a state instance.
+    * Internal constructor for a state instance.  If the parent argument is 
null
+    * the created state representing a root state in a state graph.  The 
terminal
+    * attribute declares the terminal node status of the state.  If the 
state is
+    * flagged as terminal, no sub-states or transitions may be added or 
assigned
+    * to the state.
     *
     * @paren parent the parent of the created state
     * @param name the name that the state is index under
     * @param terminal TRUE if this is a terminal state else FALSE
+    * @exception NullPointerException if the name argument is null
     */
     private DefaultState( DefaultState parent, String name, boolean terminal 
)
     {
+        if( null == name )
+        {
+            throw new NullPointerException( "name" );
+        }
         m_name = name;
         m_parent = parent;
         m_terminal = terminal;
@@ -82,7 +91,6 @@
         InvocationHandler handler = new DefaultInvocationHandler( this );
         ClassLoader classloader = getClass().getClassLoader();
         m_proxy = (State) Proxy.newProxyInstance( classloader, new Class[]{ 
State.class }, handler );
-
     }
 
    /**
@@ -114,10 +122,12 @@
     }
 
    /**
-    * Return the terminal status of this state.  If a state is termin if 
cannot
-    * contain sub-states or transitions.
+    * Return the terminal status of this state.  If a state is terminal it 
cannot
+    * contain sub-states or transitions.  Furthermore, a component declaring 
a current 
+    * state where the current state is terminal cannot change it's state 
without explicit
+    * re-initialization of the componet's service manager.
     * 
-    * @return the terminal status of this state
+    * @return TRUE if this state is a terminal state
     */
     public boolean isTerminal()
     {
@@ -126,7 +136,10 @@
 
    /**
     * Returns an array of transtion names declared in this state and all 
-    * parent states.
+    * parent states in the active state chain.  This method via the 
+    * StateManager interface (through exposeure of State) to controlling 
+    * applications.  The controlling application can apply a tranistion 
+    * by invoking the 'apply' operation on the associated ServiceManager.
     *
     * @return the available transition names
     */
@@ -193,6 +206,10 @@
     */
     private DefaultState addState( DefaultState parent, String key, boolean 
terminal )
     {
+        if( null == key )
+        {
+            throw new NullPointerException( "key" );
+        }
         if( m_parent != null )
         {
             return m_parent.addState( parent, key, terminal );
@@ -242,7 +259,9 @@
     }
 
    /**
-    * Return an array of local states contained within this state.
+    * Return an array of local states directly contained within this state
+    * instance.
+    *
     * @return the local state array
     */
     protected DefaultState[] getStates()
@@ -252,6 +271,7 @@
 
    /**
     * Return an array of all states contained within the supplied state.
+    *
     * @param parent the enclosing parent state
     * @return the state array
     */
@@ -271,7 +291,9 @@
     }
 
    /**
-    * Return a state from the state graph mathcing the supplied key.
+    * Return a state from the state graph matching the supplied key.
+    * The search does not include the root state of the state graph.
+    *
     * @param key the state key
     * @return the state assigned to the key
     * @exception NoSuchStateException if the key does not match a state
@@ -279,6 +301,10 @@
     */
     protected DefaultState getState( String key )
     {
+        if( null == key )
+        {
+            throw new NullPointerException( "key" );
+        }
         if( null != m_parent )
         {
             return m_parent.getState( key );
@@ -360,6 +386,18 @@
     */
     private void addTransition( String key, Object handler, DefaultState 
target, boolean system )
     {
+        if( null == key )
+        {
+            throw new NullPointerException( "key" );
+        }
+        if( null == handler )
+        {
+            throw new NullPointerException( "handler" );
+        }
+        if( null == target )
+        {
+            throw new NullPointerException( "target" );
+        }
         if( isTerminal() )
         {
             final String error = 
@@ -409,6 +447,10 @@
     */
     public DefaultTransition getNamedTransition( String key )
     {
+        if( null == key )
+        {
+            throw new NullPointerException( "key" );
+        }
         DefaultTransition transition = (DefaultTransition) 
m_transitions.get( key );
         if( null != transition )
         {
@@ -444,7 +486,7 @@
     {
         if( null != m_parent )
         {
-            return "[state " + m_name + " (in:" + m_parent.getName() + ")]";
+            return "[state " + m_name + " (from:" + m_parent.getName() + 
")]";
         }
         else
         {
@@ -490,7 +532,6 @@
         return m_name.hashCode();
     }
 
-
    /**
     * Untility function that returns a string representation of this state
     * in the form of a graph.

Modified: 
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
==============================================================================
--- 
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
       (original)
+++ 
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
       Mon Apr 18 17:14:44 2005
@@ -38,16 +38,34 @@
     private final Object m_handler;
     private final boolean m_system;
 
+   /**
+    * Internal utility to construct a new transition instance.  This 
constructor
+    * is used by the DefaultState state implmentation class as part of it's 
transition 
+    * factory operations.
+    *
+    * @param handler the object identifying the handler
+    * @param target the transition target state
+    * @param system if TRUE this is a system transition otherwise the 
transition
+    *    is a user (application) transition
+    */ 
     protected DefaultTransition( Object handler, DefaultState target, 
boolean system )
     {
+        if( null == handler )
+        {
+            throw new NullPointerException( "handler" );
+        }
+        if( null == target )
+        {
+            throw new NullPointerException( "target" );
+        }
         m_handler = handler;
         m_target = target;
         m_system = system;
     }
 
    /**
-    * Return the handler associated with this transition.
-    * @return the transition handler
+    * Return the handler identifier associated with this transition.
+    * @return the transition handler identfier
     */
     public Object getHandler()
     {

Modified: 
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
==============================================================================
--- 
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
  (original)
+++ 
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
  Mon Apr 18 17:14:44 2005
@@ -18,9 +18,8 @@
 
 package net.dpml.state.impl;
 
-
 /**
- * Exception thrown when a request for a handler could not be reoslved.
+ * Exception thrown when a request for a handler could not be resolved.
  *
  * @author <a href="mailto:dev-dpml AT lists.ibiblio.org";>The Digital Product 
Meta Library</a>
  */