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}