01: /*
02: * Copyright 2006 Google Inc.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
05: * use this file except in compliance with the License. You may obtain a copy of
06: * the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13: * License for the specific language governing permissions and limitations under
14: * the License.
15: */
16: package com.google.gwt.core.ext;
17:
18: /**
19: * Used to indicate that some part of a multi-step process failed. Typically,
20: * operation can continue after this exception is caught.
21: *
22: * Before throwing an object of this type, the thrower
23: * <ul>
24: * <li>must log a detailed user-facing message describing the failure,</li>
25: * <li>must report any caught exception using the logger that contributed to
26: * the failure, and </li>
27: * <li>must not include the cause of the failure in the thrown exception
28: * because (1) it will already have been associated with the detailed log entry
29: * above and (2) doing so would create a misunderstanding of how to find the
30: * causes of low-level errors in that sometimes there is an underlying an
31: * exception, sometimes not, but there can <em>always</em> be a preceding log
32: * entry. </li>
33: * </ul>
34: *
35: * After catching an object of this type, the catcher
36: * <ul>
37: * <li>can be assured that the thrower has already logged a message about the
38: * lower-level problem</li>
39: * <li>can optionally itself log a higher-level description of the process that
40: * was interrupted and the implications of the failure, and if so,</li>
41: * <li>should report this caught exception via the logger as well.</li>
42: * </ul>
43: *
44: * <pre>
45: * void lowLevel(Logger logger) throws UnableToCompleteException {
46: * try {
47: * doSomethingThatMightFail();
48: * catch (SomeException e) {
49: * // Log low-level detail and the caught exception.
50: * //
51: * logger.log("detailed problem explanation for user eyes...", e);
52: *
53: * // Do not include the caught exception.
54: * //
55: * throw new UnableToCompleteException();
56: * }
57: * }
58: *
59: * void highLevel(Logger logger) {
60: * try {
61: * // Multiple calls are shown to indicate that the process can
62: * // include any number of steps.
63: * //
64: * lowLevel(logger);
65: * lowLevel(logger);
66: * lowLevel(logger);
67: * }
68: * catch (UnableToCompleteException e) {
69: * logger.log("high-level thing failed", e);
70: * }
71: * }
72: * </pre>
73: *
74: */
75: public class UnableToCompleteException extends Exception {
76: public UnableToCompleteException() {
77: super ("(see previous log entries)");
78: }
79: }
|