    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    }