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 1790899 2017-04-10 21:56:46Z 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(Object source,
175            EventType<? extends ConfigurationEvent> type, String propertyName,
176            Object propertyValue, 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}