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 }