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     */
017    package org.apache.commons.configuration.event;
018    
019    import 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     * <code>{@link org.apache.commons.configuration.AbstractConfiguration}</code>):
052     * <dl>
053     * <dt>EVENT_ADD_PROPERTY</dt>
054     * <dd>This event is triggered for each call of the <code>addProperty()</code>
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()</code> 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()</code> 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 561230 2007-07-31 04:17:09Z rahul $
076     * @since 1.3
077     */
078    public 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</code> 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    }