1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.configuration.event; 18 19 /** 20 * <p> 21 * An event class that is used for reporting errors that occurred while 22 * processing configuration properties. 23 * </p> 24 * <p> 25 * Some configuration implementations (e.g. 26 * {@link org.apache.commons.configuration.DatabaseConfiguration} 27 * or {@link org.apache.commons.configuration.JNDIConfiguration} 28 * use an underlying storage that can throw an exception on each property 29 * access. In earlier versions of this library such exceptions were logged and 30 * then silently ignored. This makes it impossible for a client to find out that 31 * something went wrong. 32 * </p> 33 * <p> 34 * To give clients better control over the handling of errors that occur during 35 * access of a configuration object a new event listener mechanism specific for 36 * exceptions is introduced: Clients can register itself at a configuration 37 * object as an <em>error listener</em> and are then notified about all 38 * internal errors related to the source configuration object. 39 * </p> 40 * <p> 41 * By inheriting from {@code ConfigurationEvent} this event class 42 * supports all properties that describe an operation on a configuration 43 * instance. In addition a {@code Throwable} object is available 44 * representing the occurred error. The event's type determines the operation 45 * that caused the error. Note that depending on the event type and the occurred 46 * exception not all of the other properties (e.g. name of the affected property 47 * or its value) may be available. 48 * </p> 49 * 50 * @author <a 51 * href="http://commons.apache.org/configuration/team-list.html">Commons 52 * Configuration team</a> 53 * @version $Id: ConfigurationErrorEvent.java 1207610 2011-11-28 21:06:22Z oheger $ 54 * @since 1.4 55 * @see ConfigurationEvent 56 */ 57 public class ConfigurationErrorEvent extends ConfigurationEvent 58 { 59 /** 60 * The serial version UID. 61 */ 62 private static final long serialVersionUID = -7433184493062648409L; 63 64 /** Stores the exception that caused this event. */ 65 private Throwable cause; 66 67 /** 68 * Creates a new instance of {@code ConfigurationErrorEvent} and 69 * initializes it. 70 * 71 * @param source the event source 72 * @param type the event's type 73 * @param propertyName the name of the affected property 74 * @param propertyValue the value of the affected property 75 * @param cause the exception object that caused this event 76 */ 77 public ConfigurationErrorEvent(Object source, int type, 78 String propertyName, Object propertyValue, Throwable cause) 79 { 80 super(source, type, propertyName, propertyValue, true); 81 this.cause = cause; 82 } 83 84 /** 85 * Returns the cause of this error event. This is the {@code Throwable} 86 * object that caused this event to be fired. 87 * 88 * @return the cause of this error event 89 */ 90 public Throwable getCause() 91 { 92 return cause; 93 } 94 }