Exception Handling Rules

 

Digest from Axis Documentation. See Also: <<错误处理规范>>

 

Exception Handling

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.

These guidelines are fundamentally independent of programming language. They are based on experience, but proper credit must be given to More Effective C++, by Scott Meyers, for opening the eyes of the innocent(?) many years ago.

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.

 

• Primary Rule: Only Catch An Exception If You Know What To Do With It

  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...

  There are a few corrollaries to this rule.

   

  • Handle Specific Exceptions in Inner Code

    Inner code is code deep within the program. Such code should catch specific exceptions, or categories of exceptions (parents in exception hierarchies), if and only if 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.

     

  • Catch All Exceptions in Outermost Flow of Control

    Ultimately, all exceptions must be dealt with at one level or another. For command-line tools, this means the main method or program. For a middleware component, this is the entry point(s) into the component. For Axis this is AxisServlet or equivalent.

    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 log the exception. In addition to logging, the Axis Server wraps all such exceptions in AxisFaults and returns them to the client code.

    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.

   

• Catching and Logging Exceptions

  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.

  When in doubt, log the exception.

   

  • Catch and Throw

    If an exception is caught and rethrown (unresolved), logging of the exception is at the discretion of the coder and reviewers. If any comments are logged, the exception should also be logged.

    When in doubt, log the exception and any related local information that can help to identify the complete context of the exception.

    Log the exception as an error (log.error()) if it is known to be an unresolved or unresolvable error, otherwise log it at the informative level (log.info()).

     

  • Catch and Wrap

    When exception e is caught and wrapped by a new exception w, log exception e before throwing w.

    Log the exception as an error (log.error()) if it is known to be an unresolved or unresolvable error, otherwise log it at the informative level (log.info()).

     

  • Catch and Resolve

    When exception e 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 (log.info()). Issues that must be balanced are performance and problem resolvability.

    Note that in many cases, ignoring the exception may be appropriate.

     

• Respect Component Boundaries

  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.

   

  • Isolate System Logic from Business Logic

    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.

    Exceptions raised in the business logic (this includes the server and Axis handlers) must be delivered to the client code.

     

  • Protect System Code from User Code

    Protect the Axis runtime from uncontrolled user business logic. For Axis, this means that dynamically configurable handlers, providers and other user controllable hook-points must be guarded by catch(Exception ...). Exceptions generated by user code and caught by system code should be:
    • Logged, and
    • Delivered to the client program

     

  • Isolate Visibility into Server from Client

    Specific exceptions should be logged at the server side, and a more 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:
    • Client Code <--> AxisClient
    • AxisClient <--> AxisServlet (AxisServer/AxisEngine)
    • AxisServer/AxisEngine <--> Web Service

   

• Throwing Exceptions in Constructors

  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 all exceptions thrown by methods called within the constructor, cleaning up, and rethrowing the exceptions.