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