    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 *     https://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 processing configuration properties.
    022 * </p>
    023 * <p>
    024 * Some configuration implementations (for example {@link org.apache.commons.configuration2.DatabaseConfiguration} or
    025 * {@link org.apache.commons.configuration2.JNDIConfiguration} use an underlying storage that can throw an exception on
    026 * each property access. In earlier versions of this library such exceptions were logged and then silently ignored. This
    027 * makes it impossible for a client to find out that something went wrong.
    028 * </p>
    029 * <p>
    030 * To give clients better control over the handling of errors that might occur while interacting with a configuration
    031 * object, a specialized error event type is introduced. Clients can register as listeners of this event type at a
    032 * configuration object and are then notified about all internal errors related to the source configuration object.
    033 * </p>
    034 * <p>
    035 * This class defines similar properties to the {@link ConfigurationEvent} class. This makes it possible to find out
    036 * which operation was performed on a configuration causing this error event. In addition, a {@code Throwable} object is
    037 * available representing the occurred error. Note that depending on the event type and the occurred exception not all
    038 * of the other properties (for example name of the affected property or its value) may be available.
    039 * </p>
    040 *
    041 * @since 1.4
    042 * @see ConfigurationEvent
    043 */
    044public class ConfigurationErrorEvent extends Event {
    045
    046    /**
    047     * Constant for the common event type for all error events. Specific types for error events use this type as super type.
    048     *
    049     * @since 2.0
    050     */
    051    public static final EventType<ConfigurationErrorEvent> ANY = new EventType<>(Event.ANY, "ERROR");
    052
    053    /**
    054     * Constant for the event type indicating a read error. Errors of this type are generated if the underlying data store
    055     * throws an exception when reading a property.
    056     *
    057     * @since 2.0
    058     */
    059    public static final EventType<ConfigurationErrorEvent> READ = new EventType<>(ANY, "READ_ERROR");
    060
    061    /**
    062     * Constant for the event type indicating a write error. Errors of this type are generate if the underlying data store
    063     * throws an exception when updating data.
    064     *
    065     * @since 2.0
    066     */
    067    public static final EventType<ConfigurationErrorEvent> WRITE = new EventType<>(ANY, "WRITE_ERROR");
    068
    069    /**
    070     * The serial version UID.
    071     */
    072    private static final long serialVersionUID = 20140712L;
    073
    074    /** The event type of the operation which caused this error. */
    075    private final EventType<?> errorOperationType;
    076
    077    /** Stores the property name. */
    078    private final String propertyName;
    079
    080    /** Stores the property value. */
    081    private final Object propertyValue;
    082
    083    /** Stores the exception that caused this event. */
    084    private final Throwable cause;
    085
    086    /**
    087     * Creates a new instance of {@code ConfigurationErrorEvent} and sets all its properties.
    088     *
    089     * @param source the event source
    090     * @param eventType the type of this event
    091     * @param operationType the event type of the operation causing this error
    092     * @param propName the name of the affected property
    093     * @param propValue the value of the affected property
    094     * @param cause the exception object that caused this event
    095     */
    096    public ConfigurationErrorEvent(final Object source, final EventType<? extends ConfigurationErrorEvent> eventType, final EventType<?> operationType,
    097        final String propName, final Object propValue, final Throwable cause) {
    098        super(source, eventType);
    099        errorOperationType = operationType;
    100        propertyName = propName;
    101        propertyValue = propValue;
    102        this.cause = cause;
    103    }
    104
    105    /**
    106     * Gets the cause of this error event. This is the {@code Throwable} object that caused this event to be fired.
    107     *
    108     * @return the cause of this error event
    109     */
    110    public Throwable getCause() {
    111        return cause;
    112    }
    113
    114    /**
    115     * Gets the {@code EventType} of the operation which caused this error.
    116     *
    117     * @return the event type of the operation causing this error
    118     */
    119    public EventType<?> getErrorOperationType() {
    120        return errorOperationType;
    121    }
    122
    123    /**
    124     * Gets the name of the property that was accessed when this error occurred.
    125     *
    126     * @return the property name related to this error (may be <strong>null</strong>)
    127     */
    128    public String getPropertyName() {
    129        return propertyName;
    130    }
    131
    132    /**
    133     * Gets the value of the property that was accessed when this error occurred.
    134     *
    135     * @return the property value related this error (may be <strong>null</strong>)
    136     */
    137    public Object getPropertyValue() {
    138        return propertyValue;
    139    }
    140}