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}