    001    /* $Id: PluginAssertionFailure.java 729089 2008-12-23 20:22:26Z rahul $
    002     *
    003     * Licensed to the Apache Software Foundation (ASF) under one or more
    004     * contributor license agreements.  See the NOTICE file distributed with
    005     * this work for additional information regarding copyright ownership.
    006     * The ASF licenses this file to You under the Apache License, Version 2.0
    007     * (the "License"); you may not use this file except in compliance with
    008     * the License.  You may obtain a copy of the License at
    009     *
    010     *      http://www.apache.org/licenses/LICENSE-2.0
    011     *
    012     * Unless required by applicable law or agreed to in writing, software
    013     * distributed under the License is distributed on an "AS IS" BASIS,
    014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    015     * See the License for the specific language governing permissions and
    016     * limitations under the License.
    017     */
    018
    019    package org.apache.commons.digester.plugins;
    020
    021    /**
    022     * Thrown when a bug is detected in the plugins code.
    023     * <p>
    024     * This class is intended to be used in assertion statements, similar to
    025     * the way that java 1.4's native assertion mechanism is used. However there
    026     * is a difference: when a java 1.4 assertion fails, an AssertionError
    027     * is thrown, which is a subclass of Error; here, the PluginAssertionFailure
    028     * class extends RuntimeException rather than Error.
    029     * <p>
    030     * This difference in design is because throwing Error objects is not
    031     * good in a container-based architecture.
    032     * <p>
    033     * Example:
    034     * <pre>
    035     *   if (impossibleCondition) {
    036     *     throw new PluginAssertionFailure(
    037     *       "internal error: impossible condition is true");
    038     *   }
    039     * </pre>
    040     * <p>
    041     * Note that PluginAssertionFailure should <i>not</i> be thrown when user
    042     * input is bad, or when code external to the Digester module passes invalid
    043     * parameters to a plugins method. It should be used only in checks for
    044     * problems which indicate internal bugs within the plugins module.
    045     *
    046     * @since 1.6
    047     */
    048    public class PluginAssertionFailure extends RuntimeException {
    049
    050        private static final long serialVersionUID = 1L;
    051        private Throwable cause = null;
    052
    053        /**
    054         * @param cause underlying exception that caused this to be thrown
    055         */
    056        public PluginAssertionFailure(Throwable cause) {
    057            this(cause.getMessage());
    058            this.cause = cause;
    059        }
    060
    061        /**
    062         * @param msg describes the reason this exception is being thrown.
    063         */
    064        public PluginAssertionFailure(String msg) {
    065            super(msg);
    066        }
    067
    068        /**
    069         * @param msg describes the reason this exception is being thrown.
    070         * @param cause underlying exception that caused this to be thrown
    071         */
    072        public PluginAssertionFailure(String msg, Throwable cause) {
    073            this(msg);
    074            this.cause = cause;
    075        }
    076
    077        /**
    078         * Return the cause of this exception (if any) as specified in the
    079         * exception constructor.
    080         *
    081         * @since 1.8
    082         */
    083        public Throwable getCause() {
    084            return cause;
    085        }
    086    }