rsitze 02/04/30 08:30:30
Modified: java/docs developers-guide.html
Log:
Added guidelines for Exception Handling
Revision Changes Path
1.15 +156 -2 xml-axis/java/docs/developers-guide.html
Index: developers-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/developers-guide.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- developers-guide.html 25 Apr 2002 18:51:06 -0000 1.14
+++ developers-guide.html 30 Apr 2002 15:30:30 -0000 1.15
@@ -31,6 +31,7 @@
<br><a href="#General Guidelines">General Guidelines</a>
<br><a href="#Development Environment">Development Environment</a>
<br><a href="#Logging/Tracing">Logging/Tracing</a>
+<br><a href="#Exception Handling">Exception Handling</a>
<br><a href="#Compile And Run">Compile and Run</a>
<br><a href="#Internationalization">Internationalization</a>
<br><a href="#Adding Testcases">Adding Testcases</a>
@@ -293,6 +294,159 @@
</ul>
<h2>
+<a NAME="Exception Handling"></a>Exception Handling</h2>
+Guidelines for AXIS Exception Handling are based on best-practices
+for Exception Handling.
+While there are details specific to AXIS in these guidelines,
+they apply in principle to any project;
+they are included here for two reasons.
+First, because they are not listed elsewhere in the
+Apache/Jakarta guidelines (or haven't been found).
+Second, because adherence to these guidelines is
+considered crucial to enterprise ready middleware.
+<p>
+These guidelines are fundamentally independent of programming language.
+They are based on experience, but proper credit must be given to
+<i>More Effective C++</i>, by Scott Meyers,
+for opening the eyes of the innocent(?) many years ago.
+<p>
+Finally, these are guidelines.
+There will always be exceptions to these guidelines,
+in which case all that can be asked (as per these guidelines)
+is that they be logged in the form of comments in the code.
+<p>
+<ul>
+<li><h3>Primary Rule: Only Catch An Exception If You Know What To Do With
It</h3></li>
+If code catches an exception, it should know what to do with it
+at that point in the program.
+Any exception to this rule must be documented with a GOOD reason.
+Code reviewers are invited to put on their vulture beaks and peck away...
+<p>
+There are a few corrollaries to this rule.
+<p>
+<ul>
+<li><h4>Handle Specific Exceptions in Inner Code</h4></li>
+Inner code is code <i>deep</i> within the program.
+Such code should catch specific exceptions,
+or categories of exceptions (parents in exception hierarchies),
+<u>if and only if</u> the exception can be resolved
+and normal flow restored to the code.
+Note that behaviour of this sort may be significantly
+different between non-interactive code versus an interactive tool.
+<p>
+<li><h4>Catch All Exceptions in Outermost Flow of Control</h4></li>
+Ultimately, all exceptions must be dealt with at one level or another.
+For command-line tools, this means the <code>main</code>
+method or program.
+For a middleware component, this is the entry point(s) into the component.
+For AXIS this is <code>AxisServlet</code> or equivalent.
+<p>
+After catching specific exceptions which can be resolved internally,
+the outermost code must ensure that all internally generated exceptions
+are caught and handled.
+While there is generally not much that can be done,
+at a minimum the code should <u>log the exception</u>.
+In addition to logging, the AXIS Server wraps all such exceptions
+in AxisFaults and returns them
+to the client code.
+<p>
+This may seem contrary to the primary rule,
+but in fact we are claiming that AXIS does know
+what to do with this type of exception:
+exit gracefully.
+</ul>
+<p>
+<li><h3>Catching and Logging Exceptions</h3></li>
+When an Exception is going to cross a component boundry
+(client/server, or system/business logic),
+the exception must be caught and logged by the
+throwing component.
+It may then be rethrown, or wrapped, as described below.
+<p>
+When in doubt, log the exception.
+<p>
+<ul>
+<li><h4>Catch and Throw</h4></li>
+If an exception is caught, but cannot be resolved
+(and such a situation passes code review),
+and the exception is rethrown,
+logging of the exception is at the discretion of the coder and reviewers.
+If any comments are logged, the exception should also be logged.
+<p>
+<li><h4>Catch and Wrap</h4></li>
+When exception <code>e</code> is caught and wrapped
+by a new exception <code>w</code>,
+log exception <code>e</code> before throwing <code>w</code>.
+<p>
+<li><h4>Catch and Resolve</h4></li>
+When exception <code>e</code> is caught and resolved,
+logging of the exception is at the discretion of the coder and reviewers.
+If any comments are logged, the exception should also be logged.
+Issues that must be balanced are performance and problem resolvability.
+<p>
+Note that in many cases, ignoring the exception may be appropriate.
+<p>
+</ul>
+<li><h3>Respect Component Boundries</h3></li>
+There are multiple aspects of this guideline.
+On one hand, this means that business logic
+should be isolated from system logic.
+On the other hand, this means that
+client's should have limited exposure/visibility to
+implementation details of a server - particularly
+when the server is published to outside parties.
+This implies a well designed server interface.
+<p>
+<ul>
+<li><h4>Isolate System Logic from Business Logic</h4></li>
+Exceptions generated by the AXIS runtime
+should be handled, where possible,
+within the AXIS runtime.
+In the worst case the details of an exception are to be logged
+by the AXIS runtime,
+and a generally descriptive Exception raised to the Business Logic.
+<p>
+Exceptions raised in the business logic
+(this includes the server and AXIS handlers)
+must be delivered to the client code.
+<p>
+<li><h4>Protect System Code from User Code</h4></li>
+Protect the AXIS runtime from uncontrolled user business logic.
+For AXIS, this means that dynamically configurable
+<code>handlers</code>, <code>providers</code> and other
+user controllable hook-points must be guarded
+by <code>catch(Exception ...)</code>.
+Exceptions generated by user code and caught by system code should be:
+<ul>
+<li>Logged, and</li>
+<li>Delivered to the client program</li>
+</ul>
+<p>
+<li><h4>Isolate Visibility into Server from Client</h4></li>
+Specific exceptions should be logged at the server side,
+and more a general exception thrown to the client.
+This prevents clues as to the nature of the server
+(such as handlers, providers, etc)
+from being revealed to client code.
+The AXIS component boundries that should be respected are:
+<ul>
+<li>Client Code <--> AxisClient</li>
+<li>AxisClient <--> AxisServlet (AxisServer/AxisEngine)</li>
+<li>AxisServer/AxisEngine <--> Web Service</li>
+</ul>
+</ul>
+<p>
+<li><h3>Throwing Exceptions in Constructors</h3></li>
+Before throwing an exception in a constructor,
+ensure that any resources owned by the object are cleaned up.
+For objects holding resources,
+this requires catching <u>all</u> exceptions thrown by methods called
+within the constructor, cleaning up, and rethrowing the exceptions.
+<p>
+</ul>
+</ul>
+
+<h2>
<a NAME="Compile And Run"></a>Compile and Run</h2>
The <tt>xml-axis/java/build.xml</tt> file is the primary 'make' file used
by ant to build the application and run the tests. The <tt>build.xml</tt>
@@ -501,7 +655,7 @@
<br>
-<p><tt><font color="#993366"><ant
antfile="test/wsdl/Wsdl2javaTestSuite.xml"/></font></tt>
+<p><tt><font color="#993366"><ant
antfile="test/wsdl/Wsdl2javaTestSuite.xml"/></font></tt>
<p><font color="#000000">Following this clause you will see some clauses
that copy java files from the test directories. If you have additional
files, you may need to copy them over. Examine the clause that I
@@ -533,7 +687,7 @@
<br><tt><font
color="#993366">
testcase="no"></font></tt>
<br><tt><font color="#993366">
-<mapping namespace="urn:SequenceTest2" package="test.wsdl.sequence"/></font></tt>
+<mapping namespace="urn:SequenceTest2"
package="test.wsdl.sequence"/></font></tt>
<br><tt><font color="#993366"> </wsdl2java></font></tt>
<br>
<li>
