diff options
Diffstat (limited to 'branches/site-20060730-mvnbased/src/site/xdoc/exception_handling.html')
| -rw-r--r-- | branches/site-20060730-mvnbased/src/site/xdoc/exception_handling.html | 158 |
1 files changed, 0 insertions, 158 deletions
diff --git a/branches/site-20060730-mvnbased/src/site/xdoc/exception_handling.html b/branches/site-20060730-mvnbased/src/site/xdoc/exception_handling.html deleted file mode 100644 index 61a045a9fd..0000000000 --- a/branches/site-20060730-mvnbased/src/site/xdoc/exception_handling.html +++ /dev/null @@ -1,158 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Exception Handling Guidelines for The Java Runtime</title>
</head>
<body>
<h1>Java Runtime Exception Policy</h1>
<p> The key tenet of this exception policy is that exceptions should be designed with an eye - toward what the catch clause would likely do with the exception. The three main cases - are: </p>
<ul> - <li>Code Exception: Code can work around the discovered problem</li> - <li>User Exception: Problem to be remedied by a human (e.g. Administrator)</li> - <li>Assertion Exception: Problem remedied by human fixing a bug in the code</li> - </ul> - <h2>Code Exceptions</h2> - <p> These are exceptions where it is expected that some calling code may be able to - completely handle the exception, without involvement of any user. In other words, the - exception is of an alternate way of returning a value. There is a reasonable chance that - calling code (maybe a couple levels up) will be able to catch the exception and either - try again or try some other approach to accomplishing its job. Note that there may be no - way of knowing whether the caller will be able to figure out a different approach to - handling the situation. This is especially true in reusable utility code. In these - cases, the exceptions should be considered to be code exceptions. The code that handles - the exception might just turn it into a different kind of exception.</p> - <h3>Implications</h3> - <p>In general, code exceptions should be checked exceptions. They should be named based on - what happened, rather than based on who is throwing the exception. If the exception is - well named, it should be possible for the exception to be present on signatures at - several levels of a call stack and still make sense (e.g. ServiceUnavailableException).</p> - <p>There are some cases where code exceptions should not be checked exceptions. If code - cannot reasonably be expected to recover from an exception, it should be unchecked, - Also, iIf a large fraction of the methods in the code would need to declare the - exception, then its declaration doesn't add much value and so it should be a - RuntimeException so it doesn't need to be declared. One example of this kind of - exception might be a RetryException. This exception might occur on some kind of resource - conflict where retrying the transaction is likely to solve it. Since it is solved - without human involvement it is still a "code exception". </p> - <h2>User Exceptions</h2> - <p> These are exceptions that signal a problem that will be handled by a person, so the most - important component of the exception is the message, rather than the type of the - exception. Unfortunately, the code that throws the original exception often will not - have enough information to give a meaningful message to the user that has all the - necessary context. The typical "user" in this situation is an administrator, where a - stack traceback wouldn't be very helpful. Because of this, it is important that code be - littered with try/catch blocks that do no more than add context to the exception message - and then rethrow.</p> - <p>In a previous project this was done by having a base UserException class that had an - array of messages, rather than just one message. For example, code that parses an SCA - subsystem file might have a rethrow that just adds "While parsing the xyz subsystem - file". That is a message that could not be generated by the code that discovered the - problem (say an XML parsing problem), so a combination of the original message (e.g. - "Missing end tag") and the higher level message ("while parsing the xyz subsystem file") - are both necessary for know what happened. Naturally it can be any number of levels - deep.</p> - <p> The handling code for a user exception will somehow notify a user of the message and - then possibly go on. There should be different kinds of exceptions when there need to be - different ways of handling of the message or different ways to continue. Different ways - to report the error: In a server, user exceptions can often be divided according to - fault: </p> - <ul> - <li>It's the fault of the client code that is sending the incoming message (e.g. SOAP - faults).</li> - <li>It's the fault of the code or configuration that is handling the message. </li> - </ul> - <p> If the problem is the fault of the client code, then the message needs to be reported - back to the client code in a format appropriate for the client. If the problem is the - fault of the server code or configuration, then only a vague "I've got a problem here" - message should be sent to the client and the real exception message should be logged - and/or sent to an administrator. Because of the two different ways of handling the - problem, there should be different exception types. For example, ClientException could - be used for exceptions that signal problems that are the client's fault. </p> - <p> The remaining user exceptions are typically problems with configuration or the - environment. Some of them will be severe enough that the entire application needs to be - brought down, while others could be handled by just logging the problem and going on. - This difference implies that there needs to be a different exception type. Advanced - Scenario: In the case of session-scoped services, the problem is likely to require that - the instance of the service be put into an error state (like paused). This is because - subsequent messages for the service have been sent on the assumption that the previous - message actually gets processed. If some configuration error prevents a session-scoped - service from handling a single message, all future (async) messages for that service - instance should be queued up so they can be processed once the problem has been solved. </p> - <h2>Assertion Exceptions</h2> - <p> Assertion exceptions are exceptions that result from a bug in Tuscany and as such are - also intended to be solved by humans, but in this case the humans are us --are the - developers of the SCA runtime. In these cases the message isn't nearly as important, - since the stack traceback provides valuable context. If an assertion exception occurs - little can be known about the state of the server. If we wanted to be safe we would say - that assertion exceptions always bring down the entire server. However, we could play it - a little looser and say that assertion exceptions only bring down the application in - which they are discovered. </p> - - - <h2>Guidelines</h2> - <p> The following are a set of guidelines based on the above exception philosophy: </p> - <h4>1. Checked vs. unchecked exceptions</h4> - <p> Unchecked exceptions should be used when an error condition is not recoverable. Checked - exceptions thrown by third party libraries that are not recoverable should be wrapped in - unchecked exceptions rather than being propagated up the call stack. For example, an - IOException raised when reading a file might be wrapped in an unchecked LoadException - containing the name of the file. - Unchecked must always be Javadoced and declared in the throws clause of a method. </p> - <h4>2. Assertion exceptions should use the standard JDK assert facilities</h4> - <h4>3. Any exception thrown to user code must extend the appropriate Exception as defined - by the specification. This will typically be a runtime Exception.</h4> - <h4>4. No other Exceptions should be thrown to user code. Each user API method should - catch any internal exceptions and wrap them in the applicable Exception defined - by the specification. Internal exceptions must ultimately extend either TuscanyException - or TuscanyRuntimeException. - <h4>4. When possible, create clear package exception hierarchies</h4> - <p> In most cases, packages should have a clear exception hierarchy with abstract root - checked and unchecked exceptions which more specific concrete exceptions extend. - Declaring the root package exceptions abstract avoids code throwing exceptions which are - too general. Creating an exception hierarchy allows client code using a particular - package to choose the level of exception handling granularity (which in turn simplifies - the client code by avoiding unwieldy try..catch clauses). </p> - <h4> 5. Preserve all stack trace information and the original exception</h4> - <p> Exceptions must always preserve the stack trace and original exception except under - special circumstances. When wrapping exceptions to propagate, never modify the stack - trace and always include the caught exception as the cause.</p> - <h4>6. Only include local information pertinent to the failure</h4> - <p> For I18N, contextual information stored in the Exception should not be localized. It - should comprise only data pertaining to the cause, such as the name of the artifact as - above, or a key that can be used by the top level exception handler. This is needed - because the locale used to render the exception may be completely different from the - locale used by the code raising the exception. For example, an exception may be thrown - on a system whose default locale is German, logged to the system log in English but - displayed to the end user in French, Japanese, whatever their native language is. </p> - <h4>7. For exceptions that require contextual information from various code layers, either - wrap exceptions or create exceptions that can accept additional context as they are - propagated up the call stack.</h4> - <p> If a failure requires information from multiple levels, e.g. “there was an error setting - property X on component Y in module Z� do one of the following. If the initial exception - should be wrapped as it is propagated (e.g. the exception occurs at a library boundary), - add additional context information in the wrapping exception(s). If the initial - exception can be propagated, include methods for adding additional context information - as the exception is rethrown up the stack. For example, the previous failure scenario - could result in the following exception handling strategy: </p> - <ul> - <li> A component property is configured with an invalid integer type</li> - <li> The property value parsing code attempts to load an integer value using parseInt(), - resulting in a NumberFormatException</li> - <li> NumberFormatException is wrapped in an InvalidParameterException (IPE) containing - the name of the property.</li> - <li> IPE extends a more general ConfigException, which has setters for adding additional - context information such as component and module names</li> - <li> As the IPE is thrown up the stack, the component and module parsers provide - additional context information.</li> - <li> The configuration loader then wraps the IPE in a ConfigLoadExeption and provides - the source from which the configuration is being loaded.</li> - <li> The UI being used to load the configuration reports the error to the user and - displays the appropriate contextual information</li> - </ul> - <h4>8. getMessage() must return unformatted context info. If the Exception contains multiple - context fields they should be surrounded in square brackets and separated by commas, - e.g. "[ property X, component Y, module Z ]"</h4> - <h4>9. Do not override the behaviour of Throwable.toString() and Throwable.printStackTrace()</h4> - <h4>10. The java.lang.Exception base class is Serializable so all subclasses must provide - a serial UID. Any context fields must be Serializable and should be defined in the - base java namespace for JDK1.4.</h4> - <h4>11. Exceptions that wrap other Exceptions should ensure that any wrapped Exception can - be deserialized in a client environment. This may require providing a custom - writeObject method to extract any context information from the wrapped Exception - during serialization; at a minimum the message should be preserved.</h4> - </body> -</html> |