001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.configuration.event;
018    
019    /**
020     * <p>
021     * An event class that is used for reporting errors that occurred while
022     * processing configuration properties.
023     * </p>
024     * <p>
025     * Some configuration implementations (e.g.
026     * <code>{@link org.apache.commons.configuration.DatabaseConfiguration}</code>
027     * or <code>{@link org.apache.commons.configuration.JNDIConfiguration}</code>
028     * use an underlying storage that can throw an exception on each property
029     * access. In earlier versions of this library such exceptions were logged and
030     * then silently ignored. This makes it impossible for a client to find out that
031     * something went wrong.
032     * </p>
033     * <p>
034     * To give clients better control over the handling of errors that occur during
035     * access of a configuration object a new event listener mechanism specific for
036     * exceptions is introduced: Clients can register itself at a configuration
037     * object as an <em>error listener</em> and are then notified about all
038     * internal errors related to the source configuration object.
039     * </p>
040     * <p>
041     * By inheriting from <code>ConfigurationEvent</code> this event class
042     * supports all properties that describe an operation on a configuration
043     * instance. In addition a <code>Throwable</code> object is available
044     * representing the occurred error. The event's type determines the operation
045     * that caused the error. Note that depending on the event type and the occurred
046     * exception not all of the other properties (e.g. name of the affected property
047     * or its value) may be available.
048     * </p>
049     *
050     * @author <a
051     * href="http://commons.apache.org/configuration/team-list.html">Commons
052     * Configuration team</a>
053     * @version $Id: ConfigurationErrorEvent.java 561230 2007-07-31 04:17:09Z rahul $
054     * @since 1.4
055     * @see ConfigurationEvent
056     */
057    public class ConfigurationErrorEvent extends ConfigurationEvent
058    {
059        /**
060         * The serial version UID.
061         */
062        private static final long serialVersionUID = -7433184493062648409L;
063    
064        /** Stores the exception that caused this event. */
065        private Throwable cause;
066    
067        /**
068         * Creates a new instance of <code>ConfigurationErrorEvent</code> and
069         * initializes it.
070         *
071         * @param source the event source
072         * @param type the event's type
073         * @param propertyName the name of the affected property
074         * @param propertyValue the value of the affected property
075         * @param cause the exception object that caused this event
076         */
077        public ConfigurationErrorEvent(Object source, int type,
078                String propertyName, Object propertyValue, Throwable cause)
079        {
080            super(source, type, propertyName, propertyValue, true);
081            this.cause = cause;
082        }
083    
084        /**
085         * Returns the cause of this error event. This is the <code>Throwable</code>
086         * object that caused this event to be fired.
087         *
088         * @return the cause of this error event
089         */
090        public Throwable getCause()
091        {
092            return cause;
093        }
094    }