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 }