KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > core > ext > UnableToCompleteException


1 /*
2  * Copyright 2006 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
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 JavaDoc {
76   public UnableToCompleteException() {
77     super("(see previous log entries)");
78   }
79 }
80
Popular Tags