/*
 * 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)");
  }
}