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.configuration2.event; 18 19 /** 20 * <p> 21 * An event class that is used for reporting errors that occurred while processing configuration properties. 22 * </p> 23 * <p> 24 * Some configuration implementations (e.g. {@link org.apache.commons.configuration2.DatabaseConfiguration} or 25 * {@link org.apache.commons.configuration2.JNDIConfiguration} use an underlying storage that can throw an exception on 26 * each property access. In earlier versions of this library such exceptions were logged and then silently ignored. This 27 * makes it impossible for a client to find out that something went wrong. 28 * </p> 29 * <p> 30 * To give clients better control over the handling of errors that might occur while interacting with a configuration 31 * object, a specialized error event type is introduced. Clients can register as listeners of this event type at a 32 * configuration object and are then notified about all internal errors related to the source configuration object. 33 * </p> 34 * <p> 35 * This class defines similar properties to the {@link ConfigurationEvent} class. This makes it possible to find out 36 * which operation was performed on a configuration causing this error event. In addition, a {@code Throwable} object is 37 * available representing the occurred error. Note that depending on the event type and the occurred exception not all 38 * of the other properties (e.g. name of the affected property or its value) may be available. 39 * </p> 40 * 41 * @since 1.4 42 * @see ConfigurationEvent 43 */ 44 public class ConfigurationErrorEvent extends Event { 45 /** 46 * Constant for the common event type for all error events. Specific types for error events use this type as super type. 47 * 48 * @since 2.0 49 */ 50 public static final EventType<ConfigurationErrorEvent> ANY = new EventType<>(Event.ANY, "ERROR"); 51 52 /** 53 * Constant for the event type indicating a read error. Errors of this type are generated if the underlying data store 54 * throws an exception when reading a property. 55 * 56 * @since 2.0 57 */ 58 public static final EventType<ConfigurationErrorEvent> READ = new EventType<>(ANY, "READ_ERROR"); 59 60 /** 61 * Constant for the event type indicating a write error. Errors of this type are generate if the underlying data store 62 * throws an exception when updating data. 63 * 64 * @since 2.0 65 */ 66 public static final EventType<ConfigurationErrorEvent> WRITE = new EventType<>(ANY, "WRITE_ERROR"); 67 68 /** 69 * The serial version UID. 70 */ 71 private static final long serialVersionUID = 20140712L; 72 73 /** The event type of the operation which caused this error. */ 74 private final EventType<?> errorOperationType; 75 76 /** Stores the property name. */ 77 private final String propertyName; 78 79 /** Stores the property value. */ 80 private final Object propertyValue; 81 82 /** Stores the exception that caused this event. */ 83 private final Throwable cause; 84 85 /** 86 * Creates a new instance of {@code ConfigurationErrorEvent} and sets all its properties. 87 * 88 * @param source the event source 89 * @param eventType the type of this event 90 * @param operationType the event type of the operation causing this error 91 * @param propName the name of the affected property 92 * @param propValue the value of the affected property 93 * @param cause the exception object that caused this event 94 */ 95 public ConfigurationErrorEvent(final Object source, final EventType<? extends ConfigurationErrorEvent> eventType, final EventType<?> operationType, 96 final String propName, final Object propValue, final Throwable cause) { 97 super(source, eventType); 98 errorOperationType = operationType; 99 propertyName = propName; 100 propertyValue = propValue; 101 this.cause = cause; 102 } 103 104 /** 105 * Gets the {@code EventType} of the operation which caused this error. 106 * 107 * @return the event type of the operation causing this error 108 */ 109 public EventType<?> getErrorOperationType() { 110 return errorOperationType; 111 } 112 113 /** 114 * Gets the name of the property that was accessed when this error occurred. 115 * 116 * @return the property name related to this error (may be <b>null</b>) 117 */ 118 public String getPropertyName() { 119 return propertyName; 120 } 121 122 /** 123 * Gets the value of the property that was accessed when this error occurred. 124 * 125 * @return the property value related this error (may be <b>null</b>) 126 */ 127 public Object getPropertyValue() { 128 return propertyValue; 129 } 130 131 /** 132 * Gets the cause of this error event. This is the {@code Throwable} object that caused this event to be fired. 133 * 134 * @return the cause of this error event 135 */ 136 public Throwable getCause() { 137 return cause; 138 } 139 }