axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Glyn Normington" <glyn_norming...@uk.ibm.com>
Subject [Architecture Improvement] Handler lifecycle events and undo()
Date Fri, 14 Dec 2001 16:34:10 GMT
The motivation behind the following changes is to simplify the Handler
architecture and to remove certain speculative features on the basis that
we can put them back in if and when they are needed (extreme programming
refers to this as YAGNI - "You ain't gonna need it").

I've been exporing the Handler interface and especially the undo() method.
Currently, no handlers implement undo with other than a no-op. I propose to
change this by implementing undo() in the BasicHandler abstract class and
then overriding this only in the handlers which are responsible for driving
chains of "subordinate" handlers in order to propagate undo events to them
and give them the opportunity to override undo.

In general, I think most (but not all) handlers will be stateless
transformers acting on a MessageContext and that these are unlikely to need
to modify the MessageContext after a fault. That's why I want to put the
default behaviour in BasicHandler so that most handlers can just ignore
this. (I'd prefer to get rid of undo altogether, but this would appear to
be an up-hill struggle since some developers anticipate it being useful. If
anyone can give me a *real*, non-fictional example of where it will be
necessary, I'd love to hear from them.)

Furthermore, I propose to rename undo to onFault to give a better
indication of its intended use.

Also, I propose to delete the Handler init method. Any handler which
requires this can do the work either at construction time or right at the
beginning of invoke. Non-fictional counter-examples are again welcome.

Finally, I propose to delete the Handler cleanup method. If a real
requirement for this surfaces, I think we should explore an "event-driven"
approach to avoid the overhead of driving multiple no-ops in the mainline
path. Again, real examples please.

The first step towards these changes is included below and contains the
following changes:

* Rename undo to onFault in the Handler interface and BasicHandler abstract
class and implement it with a no-op in BasicHandler
* Rename undo to onFault in SimpleChain and SimpleTargetedChain
* Delete init and cleanup from Handler interface
* Delete FaultableHandler, SimpleChain, SimpleTargetedChain, and
JWSProcessor init and cleanup logic
* (Improvements to  a few comments in Handler and BasicHandler - unrelated
to this change and I'll remove them if anyone objects)

Next step (which I'll implement as soon as this patch has been committed):
* Drive onFault through "subordinate" handlers
* Remove dead code (inits, cleanups, and all or most remaining undos)

Glyn
Index: xml-axis/java/src/org/apache/axis/FaultableHandler.java
===================================================================
RCS file: /home/cvspublic/xml-axis/java/src/org/apache/axis/FaultableHandler.java,v
retrieving revision 1.29
diff -u -r1.29 FaultableHandler.java
--- xml-axis/java/src/org/apache/axis/FaultableHandler.java  2001/12/03 22:49:22 1.29
+++ xml-axis/java/src/org/apache/axis/FaultableHandler.java  2001/12/14 16:07:36
@@ -86,14 +86,6 @@
         this.workHandler = workHandler;
     }

-    public void init() {
-        workHandler.init();
-    }
-
-    public void cleanup() {
-        workHandler.cleanup();
-    }
-
     /**
      * Invokes the specified handler.  If there's a fault the appropriate
      * key will be calculated and used to find the fault chain to be
@@ -150,10 +142,10 @@
     /**
      * Some handler later on has faulted so we need to undo our work.
      */
-    public void undo(MessageContext msgContext) {
-        category.debug(JavaUtils.getMessage("enter00", "FaultableHandler::undo"));
-        workHandler.undo( msgContext );
-        category.debug(JavaUtils.getMessage("exit00", "FaultableHandler::undo"));
+    public void onFault(MessageContext msgContext) {
+        category.debug(JavaUtils.getMessage("enter00", "FaultableHandler::onFault"));
+        workHandler.onFault( msgContext );
+        category.debug(JavaUtils.getMessage("exit00", "FaultableHandler::onFault"));
     };

     public boolean canHandleBlock(QName qname) {
Index: xml-axis/java/src/org/apache/axis/Handler.java
===================================================================
RCS file: /home/cvspublic/xml-axis/java/src/org/apache/axis/Handler.java,v
retrieving revision 1.23
diff -u -r1.23 Handler.java
--- xml-axis/java/src/org/apache/axis/Handler.java      2001/11/09 23:17:47 1.23
+++ xml-axis/java/src/org/apache/axis/Handler.java      2001/12/14 16:07:36
@@ -67,17 +67,6 @@
  * @author Doug Davis (dug@us.ibm.com)
  */
 public interface Handler extends Serializable {
-    /**
-     * Init is called when the chain containing this Handler object
-     * is instantiated.
-     */
-    public void init();
-
-    /**
-     * Cleanup is called when the chain containing this Handler object
-     * is done processing the chain.
-     */
-    public void cleanup();

     /**
      * Invoke is called to do the actual work of the Handler object.
@@ -91,9 +80,9 @@
     public void invoke(MessageContext msgContext) throws AxisFault ;

     /**
-     * Called when a fault occurs to 'undo' whatever 'invoke' did.
+     * Called when a subsequent handler throws a fault.
      */
-    public void undo(MessageContext msgContext);
+    public void onFault(MessageContext msgContext);

     /**
      * Can this Handler process this QName?
@@ -102,6 +91,7 @@

     /**
      * Add the given option (name/value) to this handler's bag of options
+     * or replace the option if it is already present.
      */
     public void setOption(String name, Object value);

@@ -133,7 +123,7 @@
     public Hashtable getOptions();

     /**
-     * Sets a whole list of options
+     * Set all the options at once after removing the previous list.
      */
     public void setOptions(Hashtable opts);

Index: xml-axis/java/src/org/apache/axis/SimpleChain.java
===================================================================
RCS file: /home/cvspublic/xml-axis/java/src/org/apache/axis/SimpleChain.java,v
retrieving revision 1.35
diff -u -r1.35 SimpleChain.java
--- xml-axis/java/src/org/apache/axis/SimpleChain.java  2001/12/03 22:49:22 1.35
+++ xml-axis/java/src/org/apache/axis/SimpleChain.java  2001/12/14 16:07:36
@@ -79,16 +79,6 @@
     protected Vector     handlers ;
     protected Hashtable  options ;

-    public void init() {
-        for ( int i = 0 ; i < handlers.size() ; i++ )
-            ((Handler) handlers.elementAt( i )).init();
-    }
-
-    public void cleanup() {
-        for ( int i = 0 ; i < handlers.size() ; i++ )
-            ((Handler) handlers.elementAt( i )).cleanup();
-    }
-
     static InvocationStrategy iVisitor = new InvocationStrategy();
     static WSDLGenStrategy wsdlVisitor = new WSDLGenStrategy();

@@ -131,7 +121,7 @@
             // undo in reverse order - rethrow
             category.error( e );
             while( --i >= 0 )
-                ((Handler) handlers.elementAt( i )).undo( msgContext );
+                ((Handler) handlers.elementAt( i )).onFault( msgContext );
             throw AxisFault.makeFault(e);
         }

@@ -145,17 +135,17 @@
      * Undo all of the work this chain completed because some handler
      * later on has faulted - in reverse order.
      */
-    public void undo(MessageContext msgContext) {
+    public void onFault(MessageContext msgContext) {
         if (category.isDebugEnabled()) {
             category.debug(JavaUtils.getMessage("enter00",
-                "SimpleChain::undo"));
+                "SimpleChain::onFault"));
         }

         for ( int i = handlers.size()-1 ; i >= 0 ; i-- )
-            ((Handler) handlers.elementAt( i )).undo( msgContext );
+            ((Handler) handlers.elementAt( i )).onFault( msgContext );

         if (category.isDebugEnabled()) {
-            category.debug(JavaUtils.getMessage("exit00", "SimpleChain::undo"));
+            category.debug(JavaUtils.getMessage("exit00", "SimpleChain::onFault"));
         }
     }

Index: xml-axis/java/src/org/apache/axis/SimpleTargetedChain.java
===================================================================
RCS file: /home/cvspublic/xml-axis/java/src/org/apache/axis/SimpleTargetedChain.java,v
retrieving revision 1.33
diff -u -r1.33 SimpleTargetedChain.java
--- xml-axis/java/src/org/apache/axis/SimpleTargetedChain.java    2001/12/07 18:30:27 1.33
+++ xml-axis/java/src/org/apache/axis/SimpleTargetedChain.java    2001/12/14 16:07:36
@@ -77,18 +77,6 @@
     protected Handler    pivotHandler ;
     protected Handler    responseHandler ;

-    public void init() {
-        if ( requestHandler   != null )   requestHandler.init();
-        if ( pivotHandler != null ) pivotHandler.init();
-        if ( responseHandler  != null )  responseHandler.init();
-    }
-
-    public void cleanup() {
-        if ( requestHandler   != null )   requestHandler.cleanup();
-        if ( pivotHandler != null ) pivotHandler.cleanup();
-        if ( responseHandler  != null )  responseHandler.cleanup();
-    }
-
     /**
      * Invoke the request chain, pivot handler and response chain.  If there's
      * a fault we need to make sure that we undo any completed handler
@@ -106,7 +94,7 @@
         catch( Exception e ) {
             category.error( "SimpleTargetedChain caught exception", e );
             if ( requestHandler != null )
-                requestHandler.undo( msgContext );
+                requestHandler.onFault( msgContext );
             throw AxisFault.makeFault(e);
         }
         msgContext.setPastPivot(true);
@@ -116,9 +104,9 @@
         }
         catch( Exception e ) {
             category.error( e );
-            if ( pivotHandler != null ) pivotHandler.undo( msgContext );
+            if ( pivotHandler != null ) pivotHandler.onFault( msgContext );
             if ( requestHandler != null )
-                requestHandler.undo( msgContext );
+                requestHandler.onFault( msgContext );
             throw AxisFault.makeFault(e);
         }

@@ -139,7 +127,7 @@
         catch( Exception e ) {
             category.error( e );
             if ( requestHandler != null )
-                requestHandler.undo( msgContext );
+                requestHandler.onFault( msgContext );
             throw AxisFault.makeFault(e);
         }
         msgContext.setPastPivot(true);
@@ -160,17 +148,17 @@
     /**
      * Undo all of the work - in reverse order.
      */
-    public void undo(MessageContext msgContext) {
+    public void onFault(MessageContext msgContext) {
         if (category.isDebugEnabled()) {
-            category.debug(JavaUtils.getMessage("enter00", "SimpleTargetedChain::undo") );
+            category.debug(JavaUtils.getMessage("enter00", "SimpleTargetedChain::onFault")
);
         }

-        if ( responseHandler   != null )   responseHandler.undo( msgContext );
-        if ( pivotHandler  != null )  pivotHandler.undo( msgContext );
-        if ( requestHandler    != null )    requestHandler.undo( msgContext );
+        if ( responseHandler   != null )   responseHandler.onFault( msgContext );
+        if ( pivotHandler  != null )  pivotHandler.onFault( msgContext );
+        if ( requestHandler    != null )    requestHandler.onFault( msgContext );

         if (category.isDebugEnabled()) {
-            category.debug(JavaUtils.getMessage("exit00", "SimpleTargetedChain::undo") );
+            category.debug(JavaUtils.getMessage("exit00", "SimpleTargetedChain::onFault")
);
         }
     }

Index: xml-axis/java/src/org/apache/axis/handlers/BasicHandler.java
===================================================================
RCS file: /home/cvspublic/xml-axis/java/src/org/apache/axis/handlers/BasicHandler.java,v
retrieving revision 1.22
diff -u -r1.22 BasicHandler.java
--- xml-axis/java/src/org/apache/axis/handlers/BasicHandler.java  2001/11/09 23:17:47 1.22
+++ xml-axis/java/src/org/apache/axis/handlers/BasicHandler.java  2001/12/14 16:07:37
@@ -98,9 +98,9 @@
         return false;
     }

-    /** Must implement this in subclasses.
-     */
-    public abstract void undo(MessageContext msgContext);
+    public void onFault(MessageContext msgContext)
+    {
+    }

     /** Must implement this in subclasses.
      */
@@ -138,8 +138,11 @@
         return( options );
     }

+    /**
+     * Set all the options at once after removing the previous list.
+     */
     public void setOptions(Hashtable opts) {
-        options = opts ;
+        options = opts;
     }

     /**
Index: xml-axis/java/src/org/apache/axis/handlers/JWSProcessor.java
===================================================================
RCS file: /home/cvspublic/xml-axis/java/src/org/apache/axis/handlers/JWSProcessor.java,v
retrieving revision 1.31
diff -u -r1.31 JWSProcessor.java
--- xml-axis/java/src/org/apache/axis/handlers/JWSProcessor.java  2001/12/10 22:25:53 1.31
+++ xml-axis/java/src/org/apache/axis/handlers/JWSProcessor.java  2001/12/14 16:07:37
@@ -239,12 +239,10 @@
             */
             rpc.setOption( "methodName", "*");

-            rpc.init();   // ??
             if (doWsdl)
                 rpc.generateWSDL(msgContext);
             else
                 rpc.invoke( msgContext );
-            rpc.cleanup();  // ??
         }
         catch( Exception e ) {
             category.error( "JWSProcessor Exception", e );



Mime
View raw message