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 * @version $Id: ConfigurationErrorEvent.java 1842194 2018-09-27 22:24:23Z ggregory $ 050 * @since 1.4 051 * @see ConfigurationEvent 052 */ 053public class ConfigurationErrorEvent extends Event 054{ 055 /** 056 * Constant for the common event type for all error events. Specific types 057 * for error events use this type as super type. 058 * 059 * @since 2.0 060 */ 061 public static final EventType<ConfigurationErrorEvent> ANY = 062 new EventType<>(Event.ANY, "ERROR"); 063 064 /** 065 * Constant for the event type indicating a read error. Errors of this type 066 * are generated if the underlying data store throws an exception when 067 * reading a property. 068 * 069 * @since 2.0 070 */ 071 public static final EventType<ConfigurationErrorEvent> READ = 072 new EventType<>(ANY, "READ_ERROR"); 073 074 /** 075 * Constant for the event type indicating a write error. Errors of this type 076 * are generate if the underlying data store throws an exception when 077 * updating data. 078 * 079 * @since 2.0 080 */ 081 public static final EventType<ConfigurationErrorEvent> WRITE = 082 new EventType<>(ANY, "WRITE_ERROR"); 083 084 /** 085 * The serial version UID. 086 */ 087 private static final long serialVersionUID = 20140712L; 088 089 /** The event type of the operation which caused this error. */ 090 private final EventType<?> errorOperationType; 091 092 /** Stores the property name. */ 093 private final String propertyName; 094 095 /** Stores the property value. */ 096 private final Object propertyValue; 097 098 /** Stores the exception that caused this event. */ 099 private final Throwable cause; 100 101 /** 102 * Creates a new instance of {@code ConfigurationErrorEvent} and sets all 103 * its properties. 104 * 105 * @param source the event source 106 * @param eventType the type of this event 107 * @param operationType the event type of the operation causing this error 108 * @param propName the name of the affected property 109 * @param propValue the value of the affected property 110 * @param cause the exception object that caused this event 111 */ 112 public ConfigurationErrorEvent(final Object source, 113 final EventType<? extends ConfigurationErrorEvent> eventType, 114 final EventType<?> operationType, final String propName, final Object propValue, 115 final Throwable cause) 116 { 117 super(source, eventType); 118 errorOperationType = operationType; 119 propertyName = propName; 120 propertyValue = propValue; 121 this.cause = cause; 122 } 123 124 /** 125 * Returns the {@code EventType} of the operation which caused this error. 126 * 127 * @return the event type of the operation causing this error 128 */ 129 public EventType<?> getErrorOperationType() 130 { 131 return errorOperationType; 132 } 133 134 /** 135 * Returns the name of the property that was accessed when this error 136 * occurred. 137 * 138 * @return the property name related to this error (may be <b>null</b>) 139 */ 140 public String getPropertyName() 141 { 142 return propertyName; 143 } 144 145 /** 146 * Returns the value of the property that was accessed when this error 147 * occurred. 148 * 149 * @return the property value related this error (may be <b>null</b>) 150 */ 151 public Object getPropertyValue() 152 { 153 return propertyValue; 154 } 155 156 /** 157 * Returns the cause of this error event. This is the {@code Throwable} 158 * object that caused this event to be fired. 159 * 160 * @return the cause of this error event 161 */ 162 public Throwable getCause() 163 { 164 return cause; 165 } 166}