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.configuration2.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.configuration2.DatabaseConfiguration} or 027 * {@link org.apache.commons.configuration2.JNDIConfiguration} use an underlying 028 * storage that can throw an exception on each property access. In earlier 029 * versions of this library such exceptions were logged and then silently 030 * ignored. This makes it impossible for a client to find out that something 031 * went wrong. 032 * </p> 033 * <p> 034 * To give clients better control over the handling of errors that might occur 035 * while interacting with a configuration object, a specialized error event type 036 * is introduced. Clients can register as listeners of this event type at a 037 * configuration object and are then notified about all internal errors related 038 * to the source configuration object. 039 * </p> 040 * <p> 041 * This class defines similar properties to the {@link ConfigurationEvent} 042 * class. This makes it possible to find out which operation was performed on a 043 * configuration causing this error event. In addition, a {@code Throwable} 044 * object is available representing the occurred error. Note that depending on 045 * the event type and the occurred exception not all of the other properties 046 * (e.g. name of the affected property or its value) may be available. 047 * </p> 048 * 049 * @since 1.4 050 * @see ConfigurationEvent 051 */ 052public class ConfigurationErrorEvent extends Event 053{ 054 /** 055 * Constant for the common event type for all error events. Specific types 056 * for error events use this type as super type. 057 * 058 * @since 2.0 059 */ 060 public static final EventType<ConfigurationErrorEvent> ANY = 061 new EventType<>(Event.ANY, "ERROR"); 062 063 /** 064 * Constant for the event type indicating a read error. Errors of this type 065 * are generated if the underlying data store throws an exception when 066 * reading a property. 067 * 068 * @since 2.0 069 */ 070 public static final EventType<ConfigurationErrorEvent> READ = 071 new EventType<>(ANY, "READ_ERROR"); 072 073 /** 074 * Constant for the event type indicating a write error. Errors of this type 075 * are generate if the underlying data store throws an exception when 076 * updating data. 077 * 078 * @since 2.0 079 */ 080 public static final EventType<ConfigurationErrorEvent> WRITE = 081 new EventType<>(ANY, "WRITE_ERROR"); 082 083 /** 084 * The serial version UID. 085 */ 086 private static final long serialVersionUID = 20140712L; 087 088 /** The event type of the operation which caused this error. */ 089 private final EventType<?> errorOperationType; 090 091 /** Stores the property name. */ 092 private final String propertyName; 093 094 /** Stores the property value. */ 095 private final Object propertyValue; 096 097 /** Stores the exception that caused this event. */ 098 private final Throwable cause; 099 100 /** 101 * Creates a new instance of {@code ConfigurationErrorEvent} and sets all 102 * its properties. 103 * 104 * @param source the event source 105 * @param eventType the type of this event 106 * @param operationType the event type of the operation causing this error 107 * @param propName the name of the affected property 108 * @param propValue the value of the affected property 109 * @param cause the exception object that caused this event 110 */ 111 public ConfigurationErrorEvent(final Object source, 112 final EventType<? extends ConfigurationErrorEvent> eventType, 113 final EventType<?> operationType, final String propName, final Object propValue, 114 final Throwable cause) 115 { 116 super(source, eventType); 117 errorOperationType = operationType; 118 propertyName = propName; 119 propertyValue = propValue; 120 this.cause = cause; 121 } 122 123 /** 124 * Returns the {@code EventType} of the operation which caused this error. 125 * 126 * @return the event type of the operation causing this error 127 */ 128 public EventType<?> getErrorOperationType() 129 { 130 return errorOperationType; 131 } 132 133 /** 134 * Returns the name of the property that was accessed when this error 135 * occurred. 136 * 137 * @return the property name related to this error (may be <b>null</b>) 138 */ 139 public String getPropertyName() 140 { 141 return propertyName; 142 } 143 144 /** 145 * Returns the value of the property that was accessed when this error 146 * occurred. 147 * 148 * @return the property value related this error (may be <b>null</b>) 149 */ 150 public Object getPropertyValue() 151 { 152 return propertyValue; 153 } 154 155 /** 156 * Returns the cause of this error event. This is the {@code Throwable} 157 * object that caused this event to be fired. 158 * 159 * @return the cause of this error event 160 */ 161 public Throwable getCause() 162 { 163 return cause; 164 } 165}