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}