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 */
017package 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 */
057public 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}