    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     * {@link org.apache.commons.configuration.DatabaseConfiguration}
    027     * or {@link org.apache.commons.configuration.JNDIConfiguration}
    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} this event class
    042     * supports all properties that describe an operation on a configuration
    043     * instance. In addition a {@code Throwable} 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 1207610 2011-11-28 21:06:22Z oheger $
    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} 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}
    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    }