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