    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}