| /* |
| * Copyright 2006 Google Inc. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| * use this file except in compliance with the License. You may obtain a copy of |
| * the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| * License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| package com.google.gwt.core.ext; |
| |
| /** |
| * Used to indicate that some part of a multi-step process failed. Typically, |
| * operation can continue after this exception is caught. |
| * |
| * Before throwing an object of this type, the thrower |
| * <ul> |
| * <li>must log a detailed user-facing message describing the failure,</li> |
| * <li>must report any caught exception using the logger that contributed to |
| * the failure, and </li> |
| * <li>must not include the cause of the failure in the thrown exception |
| * because (1) it will already have been associated with the detailed log entry |
| * above and (2) doing so would create a misunderstanding of how to find the |
| * causes of low-level errors in that sometimes there is an underlying an |
| * exception, sometimes not, but there can <em>always</em> be a preceding log |
| * entry. </li> |
| * </ul> |
| * |
| * After catching an object of this type, the catcher |
| * <ul> |
| * <li>can be assured that the thrower has already logged a message about the |
| * lower-level problem</li> |
| * <li>can optionally itself log a higher-level description of the process that |
| * was interrupted and the implications of the failure, and if so,</li> |
| * <li>should report this caught exception via the logger as well.</li> |
| * </ul> |
| * |
| * <pre> |
| * void lowLevel(Logger logger) throws UnableToCompleteException { |
| * try { |
| * doSomethingThatMightFail(); |
| * catch (SomeException e) { |
| * // Log low-level detail and the caught exception. |
| * // |
| * logger.log("detailed problem explanation for user eyes...", e); |
| * |
| * // Do not include the caught exception. |
| * // |
| * throw new UnableToCompleteException(); |
| * } |
| * } |
| * |
| * void highLevel(Logger logger) { |
| * try { |
| * // Multiple calls are shown to indicate that the process can |
| * // include any number of steps. |
| * // |
| * lowLevel(logger); |
| * lowLevel(logger); |
| * lowLevel(logger); |
| * } |
| * catch (UnableToCompleteException e) { |
| * logger.log("high-level thing failed", e); |
| * } |
| * } |
| * </pre> |
| * |
| */ |
| public class UnableToCompleteException extends Exception { |
| public UnableToCompleteException() { |
| super("(see previous log entries)"); |
| } |
| } |