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 processing configuration properties.
022 * </p>
023 * <p>
024 * Some configuration implementations (e.g. {@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 (e.g. 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     * Constant for the common event type for all error events. Specific types for error events use this type as super type.
047     *
048     * @since 2.0
049     */
050    public static final EventType<ConfigurationErrorEvent> ANY = new EventType<>(Event.ANY, "ERROR");
051
052    /**
053     * Constant for the event type indicating a read error. Errors of this type are generated if the underlying data store
054     * throws an exception when reading a property.
055     *
056     * @since 2.0
057     */
058    public static final EventType<ConfigurationErrorEvent> READ = new EventType<>(ANY, "READ_ERROR");
059
060    /**
061     * Constant for the event type indicating a write error. Errors of this type are generate if the underlying data store
062     * throws an exception when updating data.
063     *
064     * @since 2.0
065     */
066    public static final EventType<ConfigurationErrorEvent> WRITE = new EventType<>(ANY, "WRITE_ERROR");
067
068    /**
069     * The serial version UID.
070     */
071    private static final long serialVersionUID = 20140712L;
072
073    /** The event type of the operation which caused this error. */
074    private final EventType<?> errorOperationType;
075
076    /** Stores the property name. */
077    private final String propertyName;
078
079    /** Stores the property value. */
080    private final Object propertyValue;
081
082    /** Stores the exception that caused this event. */
083    private final Throwable cause;
084
085    /**
086     * Creates a new instance of {@code ConfigurationErrorEvent} and sets all its properties.
087     *
088     * @param source the event source
089     * @param eventType the type of this event
090     * @param operationType the event type of the operation causing this error
091     * @param propName the name of the affected property
092     * @param propValue the value of the affected property
093     * @param cause the exception object that caused this event
094     */
095    public ConfigurationErrorEvent(final Object source, final EventType<? extends ConfigurationErrorEvent> eventType, final EventType<?> operationType,
096        final String propName, final Object propValue, final Throwable cause) {
097        super(source, eventType);
098        errorOperationType = operationType;
099        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}