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