    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 for reporting updates on a configuration object.
    022 * </p>
    023 * <p>
    024 * Event objects of this type are used for &quot;raw&quot; events, i.e. unfiltered modifications of any kind. A level
    025 * with semantically higher events (for example for property changes) may be built on top of this fundamental event mechanism.
    026 * </p>
    027 * <p>
    028 * Each event can contain the following data:
    029 * </p>
    030 * <ul>
    031 * <li>A source object, which is usually the configuration object that was modified.</li>
    032 * <li>The event's type. This is an object that corresponds to constant declarations in specific event classes. It
    033 * describes what exactly has happened.</li>
    034 * <li>If available, the name of the property whose modification caused the event.</li>
    035 * <li>If available, the value of the property that caused this event.</li>
    036 * <li>A flag whether this event was generated before or after the update of the source configuration. A modification of
    037 * a configuration typically causes two events: one event before and one event after the modification is performed. This
    038 * allows event listeners to react at the correct point of time.</li>
    039 * </ul>
    040 * <p>
    041 * The following standard events are generated by typical configuration implementations (the constants for the event
    042 * types are defined in this class:
    043 * </p>
    044 * <dl>
    045 * <dt>ADD_PROPERTY</dt>
    046 * <dd>This event is triggered for each call of the {@code addProperty()} method of a configuration object. It contains
    047 * the name of the property, to which new data is added, and the value object that is added to this property (this may
    048 * be an array or a list if multiple values are added).</dd>
    049 * <dt>SET_PROPERTY</dt>
    050 * <dd>Calling the {@code setProperty()} method triggers this event. The event object stores the name of the affected
    051 * property and its new value.</dd>
    052 * <dt>CLEAR_PROPERTY</dt>
    053 * <dd>If a property is removed from a configuration (by calling the {@code clearProperty()} method), an event of this
    054 * type is fired. In this case the event object only stores the name of the removed property, the value is
    055 * <strong>null</strong>.</dd>
    056 * <dt>CLEAR</dt>
    057 * <dd>This event is fired when the whole configuration is cleared. The corresponding event object contains no
    058 * additional data.</dd>
    059 * </dl>
    060 *
    061 * @since 1.3
    062 */
    063public class ConfigurationEvent extends Event {
    064
    065    /**
    066     * Constant for the common super type of all configuration update events.
    067     *
    068     * @since 2.0
    069     */
    070    public static final EventType<ConfigurationEvent> ANY = new EventType<>(Event.ANY, "CONFIGURATION_UPDATE");
    071
    072    /**
    073     * Constant for the event type for an add property operation.
    074     *
    075     * @since 2.0
    076     */
    077    public static final EventType<ConfigurationEvent> ADD_PROPERTY = new EventType<>(ANY, "ADD_PROPERTY");
    078
    079    /**
    080     * Constant for the event type for a set property operation.
    081     *
    082     * @since 2.0
    083     */
    084    public static final EventType<ConfigurationEvent> SET_PROPERTY = new EventType<>(ANY, "SET_PROPERTY");
    085
    086    /**
    087     * Constant for the event type for a clear property operation.
    088     *
    089     * @since 2.0
    090     */
    091    public static final EventType<ConfigurationEvent> CLEAR_PROPERTY = new EventType<>(ANY, "CLEAR_PROPERTY");
    092
    093    /**
    094     * Constant for the event type for a clear operation.
    095     *
    096     * @since 2.0
    097     */
    098    public static final EventType<ConfigurationEvent> CLEAR = new EventType<>(ANY, "CLEAR");
    099
    100    /**
    101     * Constant for the common base event type for all hierarchical update events. Events derived from this type are
    102     * generated by some specific methods of hierarchical configurations.
    103     *
    104     * @since 2.0
    105     */
    106    public static final EventType<ConfigurationEvent> ANY_HIERARCHICAL = new EventType<>(ANY, "HIERARCHICAL");
    107
    108    /**
    109     * Constant for the event type for an add nodes operation.
    110     *
    111     * @since 2.0
    112     */
    113    public static final EventType<ConfigurationEvent> ADD_NODES = new EventType<>(ANY_HIERARCHICAL, "ADD_NODES");
    114
    115    /**
    116     * Constant for the event type for a clear tree operation.
    117     *
    118     * @since 2.0
    119     */
    120    public static final EventType<ConfigurationEvent> CLEAR_TREE = new EventType<>(ANY_HIERARCHICAL, "CLEAR_TREE");
    121
    122    /**
    123     * Constant for the event type indicating a change on a sub configuration.
    124     *
    125     * @since 2.0
    126     */
    127    public static final EventType<ConfigurationEvent> SUBNODE_CHANGED = new EventType<>(ANY_HIERARCHICAL, "SUBNODE_CHANGED");
    128
    129    /**
    130     * The serial version UID.
    131     */
    132    private static final long serialVersionUID = 20140703L;
    133
    134    /** Stores the property name. */
    135    private final String propertyName;
    136
    137    /** Stores the property value. */
    138    private final Object propertyValue;
    139
    140    /** Stores the before update flag. */
    141    private final boolean beforeUpdate;
    142
    143    /**
    144     * Creates a new instance of {@code ConfigurationEvent} and initializes it.
    145     *
    146     * @param source the event source
    147     * @param type the event's type
    148     * @param propertyName the name of the affected property
    149     * @param propertyValue the value of the affected property
    150     * @param beforeUpdate the before update flag
    151     */
    152    public ConfigurationEvent(final Object source, final EventType<? extends ConfigurationEvent> type, final String propertyName, final Object propertyValue,
    153        final boolean beforeUpdate) {
    154        super(source, type);
    155        this.propertyName = propertyName;
    156        this.propertyValue = propertyValue;
    157        this.beforeUpdate = beforeUpdate;
    158    }
    159
    160    /**
    161     * Gets the name of the affected property. This can be <strong>null</strong> if no property change has lead to this event.
    162     *
    163     * @return the name of the property
    164     */
    165    public String getPropertyName() {
    166        return propertyName;
    167    }
    168
    169    /**
    170     * Gets the value of the affected property if available.
    171     *
    172     * @return the value of the property; can be <strong>null</strong>
    173     */
    174    public Object getPropertyValue() {
    175        return propertyValue;
    176    }
    177
    178    /**
    179     * Returns a flag if this event was generated before or after an update.
    180     *
    181     * @return <strong>true</strong> if this event was generated before an update; <strong>false</strong> otherwise
    182     */
    183    public boolean isBeforeUpdate() {
    184        return beforeUpdate;
    185    }
    186}