    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 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 (e.g. 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 * <b>null</b>.</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     * Constant for the common super type of all configuration update events.
    066     *
    067     * @since 2.0
    068     */
    069    public static final EventType<ConfigurationEvent> ANY = new EventType<>(Event.ANY, "CONFIGURATION_UPDATE");
    070
    071    /**
    072     * Constant for the event type for an add property operation.
    073     *
    074     * @since 2.0
    075     */
    076    public static final EventType<ConfigurationEvent> ADD_PROPERTY = new EventType<>(ANY, "ADD_PROPERTY");
    077
    078    /**
    079     * Constant for the event type for a set property operation.
    080     *
    081     * @since 2.0
    082     */
    083    public static final EventType<ConfigurationEvent> SET_PROPERTY = new EventType<>(ANY, "SET_PROPERTY");
    084
    085    /**
    086     * Constant for the event type for a clear property operation.
    087     *
    088     * @since 2.0
    089     */
    090    public static final EventType<ConfigurationEvent> CLEAR_PROPERTY = new EventType<>(ANY, "CLEAR_PROPERTY");
    091
    092    /**
    093     * Constant for the event type for a clear operation.
    094     *
    095     * @since 2.0
    096     */
    097    public static final EventType<ConfigurationEvent> CLEAR = new EventType<>(ANY, "CLEAR");
    098
    099    /**
    100     * Constant for the common base event type for all hierarchical update events. Events derived from this type are
    101     * generated by some specific methods of hierarchical configurations.
    102     *
    103     * @since 2.0
    104     */
    105    public static final EventType<ConfigurationEvent> ANY_HIERARCHICAL = new EventType<>(ANY, "HIERARCHICAL");
    106
    107    /**
    108     * Constant for the event type for an add nodes operation.
    109     *
    110     * @since 2.0
    111     */
    112    public static final EventType<ConfigurationEvent> ADD_NODES = new EventType<>(ANY_HIERARCHICAL, "ADD_NODES");
    113
    114    /**
    115     * Constant for the event type for a clear tree operation.
    116     *
    117     * @since 2.0
    118     */
    119    public static final EventType<ConfigurationEvent> CLEAR_TREE = new EventType<>(ANY_HIERARCHICAL, "CLEAR_TREE");
    120
    121    /**
    122     * Constant for the event type indicating a change on a sub configuration.
    123     *
    124     * @since 2.0
    125     */
    126    public static final EventType<ConfigurationEvent> SUBNODE_CHANGED = new EventType<>(ANY_HIERARCHICAL, "SUBNODE_CHANGED");
    127
    128    /**
    129     * The serial version UID.
    130     */
    131    private static final long serialVersionUID = 20140703L;
    132
    133    /** Stores the property name. */
    134    private final String propertyName;
    135
    136    /** Stores the property value. */
    137    private final Object propertyValue;
    138
    139    /** Stores the before update flag. */
    140    private final boolean beforeUpdate;
    141
    142    /**
    143     * Creates a new instance of {@code ConfigurationEvent} and initializes it.
    144     *
    145     * @param source the event source
    146     * @param type the event's type
    147     * @param propertyName the name of the affected property
    148     * @param propertyValue the value of the affected property
    149     * @param beforeUpdate the before update flag
    150     */
    151    public ConfigurationEvent(final Object source, final EventType<? extends ConfigurationEvent> type, final String propertyName, final Object propertyValue,
    152        final boolean beforeUpdate) {
    153        super(source, type);
    154        this.propertyName = propertyName;
    155        this.propertyValue = propertyValue;
    156        this.beforeUpdate = beforeUpdate;
    157    }
    158
    159    /**
    160     * Returns the name of the affected property. This can be <b>null</b> if no property change has lead to this event.
    161     *
    162     * @return the name of the property
    163     */
    164    public String getPropertyName() {
    165        return propertyName;
    166    }
    167
    168    /**
    169     * Returns the value of the affected property if available.
    170     *
    171     * @return the value of the property; can be <b>null</b>
    172     */
    173    public Object getPropertyValue() {
    174        return propertyValue;
    175    }
    176
    177    /**
    178     * Returns a flag if this event was generated before or after an update.
    179     *
    180     * @return <b>true</b> if this event was generated before an update; <b>false</b> otherwise
    181     */
    182    public boolean isBeforeUpdate() {
    183        return beforeUpdate;
    184    }
    185}