wood burning stoves 2.0*
The moose likes Java in General and the fly likes Exception handling guidelines Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Java in General
Bookmark "Exception handling guidelines" Watch "Exception handling guidelines" New topic
Author

Exception handling guidelines

Sean Sullivan
Ranch Hand

Joined: Sep 09, 2001
Posts: 427
I am in the process of establishing
"Exception Handling Guidelines" (best practices)
for my company.
Josh Bloch has some _exceptional_ advice in his
book "Effective Java"
Also, I found this information in the Apache AXIS
project.
Enjoy.

Guidelines for Exception Handling
=================================
This text came from http://xml.apache.org/axis/
{{
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 Boundries
===========================
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 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:
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.
}}
Detlef Winkelvoss
Greenhorn

Joined: Sep 09, 2002
Posts: 2
Hi Sean,
a good concept paper for exception handling i miss also,
nevertheless i find it's a good idea to see the problem more from general aspect of error handling.
A good introduction comes from Erhard Keller:
http://www.objectarchitects.de/arcus/cookbook/exhandling/index.htm
I hope that's help you.
wbr. winkel
 
 
subject: Exception handling guidelines