DPML Notify

[mcconnell AT dpml.net]

Author: mcconnell AT dpml.net
Date: Mon Apr 18 21:21:05 2005
New Revision: 2320

Modified:
   
development/main/metro/composition/testing/activity/src/main/net/dpml/test/Component.java
   
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/test/net/dpml/state/impl/DefaultStateTestCase.java
Log:
Improve type safety in the DefaultTransition implementation and introduce 
uris as the formal mechanism for declaring the handler associated with a 
transition.

Modified: 
development/main/metro/composition/testing/activity/src/main/net/dpml/test/Component.java
==============================================================================
--- 
development/main/metro/composition/testing/activity/src/main/net/dpml/test/Component.java
   (original)
+++ 
development/main/metro/composition/testing/activity/src/main/net/dpml/test/Component.java
   Mon Apr 18 21:21:05 2005
@@ -79,19 +79,14 @@
             return STATE;
         }
 
+        //
+        // Override the default initialize method with an demo of the 
+        // optional registration of a generic transition handler.
+        //
+
         public void initialize() throws Exception
         {
-            //
-            // An example of the registration of a handler instance
-            //
-
-            ExampleHandler terminator = new ExampleHandler( "terminator" );
-            addRegisteredHandler( "terminate", terminator );
-
-            //
-            // continue with normal initialization
-            //
- 
+            addRegisteredHandler( "terminate", GENERIC_HANDLER );
             super.initialize();
         }
     }
@@ -148,39 +143,32 @@
 
         //
         // create the handler declarations and add then under transitions
-        // (we are declaring method based execution because this is the 
-        // only strategy currently implementated but the idea is to support 
-        // registered handlers and/or delegation to identified parts)
         //
 
         try
         {
-            URI initialize = new URI( "method:null" );
-            URI terminate = new URI( "handler:terminate" );
-            URI start = new URI( "method:start" );
-            URI stop = new URI( "method:stop" );
-
             //
             // add system transitions dealing with initilization and 
-            // termination
+            // termination - each transition is added to a particular 
+            // state and is qualified with the uri of the handler to 
+            // use, and the transitions target state
             //
 
-            root.addTerminatingTransition( terminate, terminated );
-            root.addInitializingTransition( initialize, initialized );
-            started.addTerminatingTransition( stop, stopped );
+            root.addTerminatingTransition( new URI( "handler:terminate" ), 
terminated );
+            root.addInitializingTransition( new URI( "method:null" ), 
initialized );
+            started.addTerminatingTransition( new URI( "method:stop" ), 
stopped );
 
             //
             // add user (application) transitions
             //
 
-            initialized.addTransition( "start", start, started );
-            started.addTransition( "stop", stop, stopped );
-            stopped.addTransition( "start", start, started );
+            initialized.addTransition( "start", new URI( "method:start" ), 
started );
+            started.addTransition( "stop", new URI( "method:stop" ), stopped 
);
+            stopped.addTransition( "start", new URI( "method:start" ), 
started );
         }
         catch( URISyntaxException e )
         {
-            // will not happen
-            e.printStackTrace();
+            e.printStackTrace(); // will not happen
             return null;
         }
 
@@ -189,26 +177,21 @@
 
     //
     // The following class is an example of a transition handler.  Instances
-    // of this class may be registered with the state manager and referend 
in 
-    // transition via the urn "handler:[key]".
+    // of this class may be registered with the state manager and referenced 
in 
+    // transitiond via the urn "handler:[key]".
     //
 
-    public static class ExampleHandler
-    {
-        final String m_name;
-
-        public ExampleHandler( String name )
-        {
-            m_name = name;
-        }
+    private static final Handler GENERIC_HANDLER = new Handler();
 
+    public static class Handler
+    {
         public void handle( Component instance, State state, State target, 
Logger logger )
         {
             final String message = 
-              "transitioning to [" 
+              "handling transition from [" 
+              + state.getName()
+              + "] to ["
               + target.getName()
-              + "] via handler ["
-              + m_name
               + "]";
             logger.info( message );
         }

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 21:21:05 2005
@@ -235,7 +235,7 @@
     {
         DefaultState state = getCurrentState();
         DefaultTransition transition = state.getNamedTransition( key );
-        Object handler = transition.getHandler();
+        URI handler = transition.getHandlerURI();
         DefaultState target = transition.getTransitionTarget();
         if( state.equals( target ) )
         {
@@ -246,11 +246,11 @@
             if( getLogger().isLoggable( Level.FINE ) )
             {
                 final String message = 
-                  "applying "
+                  "applying ["
                   + handler.toString()
-                  + "' to '" 
+                  + "] to state [" 
                   + state.getName() 
-                  + "'";
+                  + "]";
                 getLogger().fine( message );
             }
             Logger logger = getLogger();
@@ -280,76 +280,64 @@
     * @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
+    private void execute( URI uri, State state, State target, Logger logger 
) throws Exception
     {
-         if( handler instanceof URI )
+         String scheme = uri.getScheme();
+         if( "part".equals( scheme ) )
          {
-             URI uri = (URI) handler;
-             String scheme = uri.getScheme();
-             if( "part".equals( scheme ) )
-             {
-                 //
-                 // delegate transition execution to an identified part
-                 //
+             //
+             // delegate transition execution to an identified part
+             //
 
-                 throw new UnsupportedOperationException( uri.toString() );
-             }
-             else if( "handler".equals( scheme ) )
-             {
-                 //
-                 // delegate execution to an registered handler
-                 //
+             throw new UnsupportedOperationException( uri.toString() );
+         }
+         else if( "handler".equals( scheme ) )
+         {
+             //
+             // delegate execution to an registered handler
+             //
 
-                 String spec = uri.getSchemeSpecificPart();
-                 if( "null".equals( spec ) )
-                 {
-                     return;
-                 }
-                 else
-                 {
-                     Object h = getRegisteredHandler( spec );
-                     Class c = h.getClass();
-                     Method method = locateMethod( c, "handle" );
-                     Class[] parameters = method.getParameterTypes();
-                     Object[] args = resolveArguments( parameters, state, 
target, logger );
-                     method.invoke( h, args );
-                 }
+             String spec = uri.getSchemeSpecificPart();
+             if( "null".equals( spec ) )
+             {
+                 return;
              }
-             else if( "method".equals( scheme ) )
+             else
              {
-                 //
-                 // invoke the named method on the component instance
-                 //
+                 Object h = getRegisteredHandler( spec );
+                 Class c = h.getClass();
+                 Method method = locateMethod( c, "handle" );
+                 Class[] parameters = method.getParameterTypes();
+                 Object[] args = resolveArguments( parameters, state, 
target, logger );
+                 method.invoke( h, args );
+             }
+         }
+         else if( "method".equals( scheme ) )
+         {
+             //
+             // invoke the named method on the component instance
+             //
 
-                 String spec = uri.getSchemeSpecificPart();
-                 if( "null".equals( spec ) )
-                 {
-                     return;
-                 }
-                 else
-                 {
-                     Class c = m_instance.getClass();
-                     Method method = locateMethod( c, spec );
-                     Class[] parameters = method.getParameterTypes();
-                     Object[] args = resolveArguments( parameters, state, 
target, logger );
-                     method.invoke( m_instance, args );
-                 }
+             String spec = uri.getSchemeSpecificPart();
+             if( "null".equals( spec ) )
+             {
+                 return;
              }
              else
              {
-                 final String error = 
-                   "Scheme not recognized."
-                   + "\nScheme: " + scheme
-                   + "\nURI: " + uri;
-                 throw new IllegalArgumentException( error );
+                 Class c = m_instance.getClass();
+                 Method method = locateMethod( c, spec );
+                 Class[] parameters = method.getParameterTypes();
+                 Object[] args = resolveArguments( parameters, state, 
target, logger );
+                 method.invoke( m_instance, args );
              }
          }
          else
          {
              final String error = 
-               "Handler class not supported."
-               + "\nClass: " + handler.getClass().getName()
-               + "\nComponent Class: " + m_instance.getClass().getName();
+               "Scheme not recognized."
+               + "\nScheme: " + scheme
+               + "\nURI: " + uri;
              throw new IllegalArgumentException( error );
          }
     }

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 21:21:05 2005
@@ -24,6 +24,7 @@
 import java.util.ArrayList;
 import java.lang.reflect.InvocationHandler;
 import java.lang.reflect.Proxy;
+import java.net.URI;
 
 import net.dpml.state.State;
 import net.dpml.state.NoSuchStateException;
@@ -335,12 +336,13 @@
     * transitions until either no terminating traistion is found or a 
terminal state 
     * is reached.
     *
-    * @param handler the object to be assigned as the handler of the 
transition action
+    * @param uri the uri identifying the handler to be assigned as the 
handler 
+    *    of the transition action
     * @param target the transition target state 
     */
-    public void addTerminatingTransition( Object handler, DefaultState 
target )
+    public void addTerminatingTransition( URI uri, DefaultState target )
     {
-        addTransition( "terminate", handler, target, true );
+        addTransition( "terminate", uri, target, true );
     }
 
    /**
@@ -354,12 +356,13 @@
     * non-terminal state, the state manager will attempt to locate and apply 
initiazation 
     * transitions until no further initilizations transitions are reachable.
     *
-    * @param handler the object to be assigned as the handler of the 
transition action
+    * @param uri the uri identifying the handler to be assigned as the 
handler 
+    *    of the transition action
     * @param target the transition target state 
     */
-    public void addInitializingTransition( Object handler, DefaultState 
target )
+    public void addInitializingTransition( URI uri, DefaultState target )
     {
-        addTransition( "initialize", handler, target, true );
+        addTransition( "initialize", uri, target, true );
     }
 
    /**
@@ -369,30 +372,32 @@
     * selcting transitions.
     *
     * @param key the transition key
-    * @param handler the object to be assinged as the handler of the 
transition action
+    * @param uri the uri identifying the handler to be assigned as the 
handler 
+    *    of the transition action
     * @param target the transition target state 
     */
-    public void addTransition( String key, Object handler, DefaultState 
target )
+    public void addTransition( String key, URI uri, DefaultState target )
     {
-        addTransition( key, handler, target, false );
+        addTransition( key, uri, target, false );
     }
 
    /**
     * Internal function to add a transition to the state. 
     *
     * @param key the transition key
-    * @param handler the object to be assinged as the handler of the 
transition action
+    * @param uri the uri identifying the handler to be assingned as the 
+    *    handler of the transition action
     * @param target the transition target state 
     */
-    private void addTransition( String key, Object handler, DefaultState 
target, boolean system )
+    private void addTransition( String key, URI uri, DefaultState target, 
boolean system )
     {
         if( null == key )
         {
             throw new NullPointerException( "key" );
         }
-        if( null == handler )
+        if( null == uri )
         {
-            throw new NullPointerException( "handler" );
+            throw new NullPointerException( "uri" );
         }
         if( null == target )
         {
@@ -414,11 +419,12 @@
             {
                 final String error = 
                   "The supplied key is a reserved transition name."
-                  + "\nKey: " + key;
+                  + "\nKey: " + key
+                  + "\nHandler URI: " + uri;
                 throw new IllegalArgumentException( error );
             }
         }
-        DefaultTransition transition = new DefaultTransition( handler, 
target, system );
+        DefaultTransition transition = new DefaultTransition( uri, target, 
system );
         m_transitions.put( key, transition );
     }
 

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 21:21:05 2005
@@ -22,6 +22,7 @@
 import java.util.Hashtable;
 import java.util.TreeMap;
 import java.util.ArrayList;
+import java.net.URI;
 
 import net.dpml.state.State;
 import net.dpml.state.Transition;
@@ -35,7 +36,7 @@
 public class DefaultTransition implements Transition
 {
     private final DefaultState m_target;
-    private final Object m_handler;
+    private final URI m_handler;
     private final boolean m_system;
 
    /**
@@ -43,12 +44,12 @@
     * is used by the DefaultState state implmentation class as part of it's 
transition 
     * factory operations.
     *
-    * @param handler the object identifying the handler
+    * @param handler the uri 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 )
+    protected DefaultTransition( URI handler, DefaultState target, boolean 
system )
     {
         if( null == handler )
         {
@@ -64,10 +65,10 @@
     }
 
    /**
-    * Return the handler identifier associated with this transition.
+    * Return the handler uri identifier associated with this transition.
     * @return the transition handler identfier
     */
-    public Object getHandler()
+    public URI getHandlerURI()
     {
         return m_handler;
     }

Modified: 
development/main/metro/state/impl/src/test/net/dpml/state/impl/DefaultStateTestCase.java
==============================================================================
--- 
development/main/metro/state/impl/src/test/net/dpml/state/impl/DefaultStateTestCase.java
    (original)
+++ 
development/main/metro/state/impl/src/test/net/dpml/state/impl/DefaultStateTestCase.java
    Mon Apr 18 21:21:05 2005
@@ -18,6 +18,9 @@
 
 package net.dpml.state.impl;
 
+import java.net.URI;
+import java.util.logging.Logger;
+
 import junit.framework.TestCase;
 
 import net.dpml.state.State;
@@ -50,32 +53,23 @@
         // create the operations and add then under transitions
         //
 
-        Operation initialize = new Operation( "initialize" );
-        Operation terminate = new Operation( "terminate" );
-        Operation start = new Operation( "start" );
-        Operation stop = new Operation( "stop" );
-
-        root.addInitializingTransition( initialize, initialized );
-        root.addTerminatingTransition( terminate, terminated );
-
-        initialized.addTransition( "start", start, started );
-        started.addTransition( "stop", stop, stopped );
-        stopped.addTransition( "start", start, started );
+        root.addInitializingTransition( new URI( "handler:demo" ), 
initialized );
+        initialized.addTerminatingTransition( new URI( "handler:demo" ), 
terminated );
+        available.addTransition( "start", new URI( "handler:demo" ), started 
);
+        started.addTransition( "stop", new URI( "handler:demo" ), stopped );
+        stopped.addTransition( "start", new URI( "handler:demo" ), started );
 
         String audit = root.list();
         System.out.println( audit );
     }
 
+    public static Operation demo = new Operation();
+
     private static class Operation
     {
-        final String m_name;
-        public Operation( String name )
-        {
-            m_name = name;
-        }
-        public void execute()
+        public void handle( Logger logger, State state, State target )
         {
-            System.out.println( "executing " + m_name );
+            System.out.println( "transitioning to " + target );
         }
     }
 }