View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.configuration.event;
    18
    19  import java.util.EventObject;
    20
    21  /***
    22   * <p>
    23   * An event class for reporting updates on a configuration object.
    24   * </p>
    25   * <p>
    26   * Event objects of this type are used for &quot;raw&quot; events, i.e.
    27   * unfiltered modifications of any kind. A level with semantically higher events
    28   * (e.g. for property changes) may be built on top of this fundamental event
    29   * mechanism.
    30   * </p>
    31   * <p>
    32   * Each event can contain the following data:
    33   * <ul>
    34   * <li>A source object, which is usually the configuration object that was
    35   * modified.</li>
    36   * <li>The event's type. This is a numeric value that corresponds to constant
    37   * declarations in concrete configuration classes. It describes what exactly has
    38   * happended.</li>
    39   * <li>If available, the name of the property whose modification caused the
    40   * event.</li>
    41   * <li>If available, the value of the property that caused this event.</li>
    42   * <li>A flag whether this event was generated before or after the update of
    43   * the source configuration. A modification of a configuration typically causes
    44   * two events: one event before and one event after the modification is
    45   * performed. This allows event listeners to react at the correct point of time.</li>
    46   * </ul>
    47   * </p>
    48   * <p>
    49   * The following standard events are generated by typical configuration
    50   * implementations (the constants for the event types are defined in
    51   * <code>{@link org.apache.commons.configuration.AbstractConfiguration}</code>):
    52   * <dl>
    53   * <dt>EVENT_ADD_PROPERTY</dt>
    54   * <dd>This event is triggered for each call of the <code>addProperty()</code>
    55   * method of a configuration object. It contains the name of the property, to
    56   * which new data is added, and the value object that is added to this property
    57   * (this may be an array or a list if multiple values are added).</dd>
    58   * <dt>EVENT_SET_PROPERTY</dt>
    59   * <dd>Calling the <code>setProperty()</code> method triggers this event. The
    60   * event object stores the name of the affected property and its new value.</dd>
    61   * <dt>EVENT_CLEAR_PROPERTY</dt>
    62   * <dd>If a property is removed from a configuration (by calling the
    63   * <code>clearProperty()</code> method), an event of this type is fired. In
    64   * this case the event object only stores the name of the removed property, the
    65   * value is <b>null</b>.</dd>
    66   * <dt>EVENT_CLEAR</dt>
    67   * <dd>This event is fired when the whole configuration is cleared. The
    68   * corresponding event object contains no additional data.</dd>
    69   * </dl>
    70   * </p>
    71   *
    72   * @author <a
    73   * href="http://commons.apache.org/configuration/team-list.html">Commons
    74   * Configuration team</a>
    75   * @version $Id: ConfigurationEvent.java 561230 2007-07-31 04:17:09Z rahul $
    76   * @since 1.3
    77   */
    78  public class ConfigurationEvent extends EventObject
    79  {
    80      /***
    81       * The serial version UID.
    82       */
    83      private static final long serialVersionUID = 3277238219073504136L;
    84
    85      /*** Stores the event type. */
    86      private int type;
    87
    88      /*** Stores the property name. */
    89      private String propertyName;
    90
    91      /*** Stores the property value. */
    92      private Object propertyValue;
    93
    94      /*** Stores the before update flag. */
    95      private boolean beforeUpdate;
    96
    97      /***
    98       * Creates a new instance of <code>ConfigurationEvent</code> and
    99       * 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 }