Return-Path: Delivered-To: apmail-xml-axis-dev-archive@xml.apache.org Received: (qmail 61297 invoked by uid 500); 14 Dec 2001 16:32:59 -0000 Mailing-List: contact axis-dev-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: axis-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list axis-dev@xml.apache.org Received: (qmail 61288 invoked from network); 14 Dec 2001 16:32:57 -0000 Subject: [Architecture Improvement] Handler lifecycle events and undo() To: axis-dev@xml.apache.org X-Mailer: Lotus Notes Release 5.0.7 March 21, 2001 Message-ID: From: "Glyn Normington" Date: Fri, 14 Dec 2001 16:34:10 +0000 X-MIMETrack: Serialize by Router on d06ml007/06/M/IBM(Release 5.0.8 |June 18, 2001) at 14/12/2001 16:32:52 MIME-Version: 1.0 Content-type: text/plain; charset=us-ascii X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 );