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}