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.configuration.event;
018
019import java.util.EventObject;
020
021/**
022 * <p>
023 * An event class for reporting updates on a configuration object.
024 * </p>
025 * <p>
026 * Event objects of this type are used for &quot;raw&quot; events, i.e.
027 * unfiltered modifications of any kind. A level with semantically higher events
028 * (e.g. for property changes) may be built on top of this fundamental event
029 * mechanism.
030 * </p>
031 * <p>
032 * Each event can contain the following data:
033 * <ul>
034 * <li>A source object, which is usually the configuration object that was
035 * modified.</li>
036 * <li>The event's type. This is a numeric value that corresponds to constant
037 * declarations in concrete configuration classes. It describes what exactly has
038 * happended.</li>
039 * <li>If available, the name of the property whose modification caused the
040 * event.</li>
041 * <li>If available, the value of the property that caused this event.</li>
042 * <li>A flag whether this event was generated before or after the update of
043 * the source configuration. A modification of a configuration typically causes
044 * two events: one event before and one event after the modification is
045 * performed. This allows event listeners to react at the correct point of time.</li>
046 * </ul>
047 * </p>
048 * <p>
049 * The following standard events are generated by typical configuration
050 * implementations (the constants for the event types are defined in
051 * {@link org.apache.commons.configuration.AbstractConfiguration}):
052 * <dl>
053 * <dt>EVENT_ADD_PROPERTY</dt>
054 * <dd>This event is triggered for each call of the {@code addProperty()}
055 * method of a configuration object. It contains the name of the property, to
056 * which new data is added, and the value object that is added to this property
057 * (this may be an array or a list if multiple values are added).</dd>
058 * <dt>EVENT_SET_PROPERTY</dt>
059 * <dd>Calling the {@code setProperty()} method triggers this event. The
060 * event object stores the name of the affected property and its new value.</dd>
061 * <dt>EVENT_CLEAR_PROPERTY</dt>
062 * <dd>If a property is removed from a configuration (by calling the
063 * {@code clearProperty()} method), an event of this type is fired. In
064 * this case the event object only stores the name of the removed property, the
065 * value is <b>null</b>.</dd>
066 * <dt>EVENT_CLEAR</dt>
067 * <dd>This event is fired when the whole configuration is cleared. The
068 * corresponding event object contains no additional data.</dd>
069 * </dl>
070 * </p>
071 *
072 * @author <a
073 * href="http://commons.apache.org/configuration/team-list.html">Commons
074 * Configuration team</a>
075 * @version $Id: ConfigurationEvent.java 1207610 2011-11-28 21:06:22Z oheger $
076 * @since 1.3
077 */
078public class ConfigurationEvent extends EventObject
079{
080    /**
081     * The serial version UID.
082     */
083    private static final long serialVersionUID = 3277238219073504136L;
084
085    /** Stores the event type. */
086    private int type;
087
088    /** Stores the property name. */
089    private String propertyName;
090
091    /** Stores the property value. */
092    private Object propertyValue;
093
094    /** Stores the before update flag. */
095    private boolean beforeUpdate;
096
097    /**
098     * Creates a new instance of {@code ConfigurationEvent} and
099     * initializes it.
100     *
101     * @param source the event source
102     * @param type the event's type
103     * @param propertyName the name of the affected property
104     * @param propertyValue the value of the affected property
105     * @param beforeUpdate the before update flag
106     */
107    public ConfigurationEvent(Object source, int type, String propertyName,
108            Object propertyValue, boolean beforeUpdate)
109    {
110        super(source);
111        this.type = type;
112        this.propertyName = propertyName;
113        this.propertyValue = propertyValue;
114        this.beforeUpdate = beforeUpdate;
115    }
116
117    /**
118     * Returns the name of the affected property. This can be <b>null</b> if no
119     * property change has lead to this event.
120     *
121     * @return the name of the property
122     */
123    public String getPropertyName()
124    {
125        return propertyName;
126    }
127
128    /**
129     * Returns the value of the affected property if available.
130     *
131     * @return the value of the property; can be <b>null</b>
132     */
133    public Object getPropertyValue()
134    {
135        return propertyValue;
136    }
137
138    /**
139     * Returns the type of this event. This describes the update process that
140     * caused this event.
141     *
142     * @return the event's type
143     */
144    public int getType()
145    {
146        return type;
147    }
148
149    /**
150     * Returns a flag if this event was generated before or after an update.
151     *
152     * @return <b>true</b> if this event was generated before an update;
153     * <b>false</b> otherwise
154     */
155    public boolean isBeforeUpdate()
156    {
157        return beforeUpdate;
158    }
159}