ConfigurationEvent.java

  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.configuration2.event;

  18. /**
  19.  * <p>
  20.  * An event class for reporting updates on a configuration object.
  21.  * </p>
  22.  * <p>
  23.  * Event objects of this type are used for &quot;raw&quot; events, i.e. unfiltered modifications of any kind. A level
  24.  * with semantically higher events (for example for property changes) may be built on top of this fundamental event mechanism.
  25.  * </p>
  26.  * <p>
  27.  * Each event can contain the following data:
  28.  * </p>
  29.  * <ul>
  30.  * <li>A source object, which is usually the configuration object that was modified.</li>
  31.  * <li>The event's type. This is an object that corresponds to constant declarations in specific event classes. It
  32.  * describes what exactly has happened.</li>
  33.  * <li>If available, the name of the property whose modification caused the event.</li>
  34.  * <li>If available, the value of the property that caused this event.</li>
  35.  * <li>A flag whether this event was generated before or after the update of the source configuration. A modification of
  36.  * a configuration typically causes two events: one event before and one event after the modification is performed. This
  37.  * allows event listeners to react at the correct point of time.</li>
  38.  * </ul>
  39.  * <p>
  40.  * The following standard events are generated by typical configuration implementations (the constants for the event
  41.  * types are defined in this class:
  42.  * </p>
  43.  * <dl>
  44.  * <dt>ADD_PROPERTY</dt>
  45.  * <dd>This event is triggered for each call of the {@code addProperty()} method of a configuration object. It contains
  46.  * the name of the property, to which new data is added, and the value object that is added to this property (this may
  47.  * be an array or a list if multiple values are added).</dd>
  48.  * <dt>SET_PROPERTY</dt>
  49.  * <dd>Calling the {@code setProperty()} method triggers this event. The event object stores the name of the affected
  50.  * property and its new value.</dd>
  51.  * <dt>CLEAR_PROPERTY</dt>
  52.  * <dd>If a property is removed from a configuration (by calling the {@code clearProperty()} method), an event of this
  53.  * type is fired. In this case the event object only stores the name of the removed property, the value is
  54.  * <strong>null</strong>.</dd>
  55.  * <dt>CLEAR</dt>
  56.  * <dd>This event is fired when the whole configuration is cleared. The corresponding event object contains no
  57.  * additional data.</dd>
  58.  * </dl>
  59.  *
  60.  * @since 1.3
  61.  */
  62. public class ConfigurationEvent extends Event {
  63.     /**
  64.      * Constant for the common super type of all configuration update events.
  65.      *
  66.      * @since 2.0
  67.      */
  68.     public static final EventType<ConfigurationEvent> ANY = new EventType<>(Event.ANY, "CONFIGURATION_UPDATE");

  69.     /**
  70.      * Constant for the event type for an add property operation.
  71.      *
  72.      * @since 2.0
  73.      */
  74.     public static final EventType<ConfigurationEvent> ADD_PROPERTY = new EventType<>(ANY, "ADD_PROPERTY");

  75.     /**
  76.      * Constant for the event type for a set property operation.
  77.      *
  78.      * @since 2.0
  79.      */
  80.     public static final EventType<ConfigurationEvent> SET_PROPERTY = new EventType<>(ANY, "SET_PROPERTY");

  81.     /**
  82.      * Constant for the event type for a clear property operation.
  83.      *
  84.      * @since 2.0
  85.      */
  86.     public static final EventType<ConfigurationEvent> CLEAR_PROPERTY = new EventType<>(ANY, "CLEAR_PROPERTY");

  87.     /**
  88.      * Constant for the event type for a clear operation.
  89.      *
  90.      * @since 2.0
  91.      */
  92.     public static final EventType<ConfigurationEvent> CLEAR = new EventType<>(ANY, "CLEAR");

  93.     /**
  94.      * Constant for the common base event type for all hierarchical update events. Events derived from this type are
  95.      * generated by some specific methods of hierarchical configurations.
  96.      *
  97.      * @since 2.0
  98.      */
  99.     public static final EventType<ConfigurationEvent> ANY_HIERARCHICAL = new EventType<>(ANY, "HIERARCHICAL");

  100.     /**
  101.      * Constant for the event type for an add nodes operation.
  102.      *
  103.      * @since 2.0
  104.      */
  105.     public static final EventType<ConfigurationEvent> ADD_NODES = new EventType<>(ANY_HIERARCHICAL, "ADD_NODES");

  106.     /**
  107.      * Constant for the event type for a clear tree operation.
  108.      *
  109.      * @since 2.0
  110.      */
  111.     public static final EventType<ConfigurationEvent> CLEAR_TREE = new EventType<>(ANY_HIERARCHICAL, "CLEAR_TREE");

  112.     /**
  113.      * Constant for the event type indicating a change on a sub configuration.
  114.      *
  115.      * @since 2.0
  116.      */
  117.     public static final EventType<ConfigurationEvent> SUBNODE_CHANGED = new EventType<>(ANY_HIERARCHICAL, "SUBNODE_CHANGED");

  118.     /**
  119.      * The serial version UID.
  120.      */
  121.     private static final long serialVersionUID = 20140703L;

  122.     /** Stores the property name. */
  123.     private final String propertyName;

  124.     /** Stores the property value. */
  125.     private final Object propertyValue;

  126.     /** Stores the before update flag. */
  127.     private final boolean beforeUpdate;

  128.     /**
  129.      * Creates a new instance of {@code ConfigurationEvent} and initializes it.
  130.      *
  131.      * @param source the event source
  132.      * @param type the event's type
  133.      * @param propertyName the name of the affected property
  134.      * @param propertyValue the value of the affected property
  135.      * @param beforeUpdate the before update flag
  136.      */
  137.     public ConfigurationEvent(final Object source, final EventType<? extends ConfigurationEvent> type, final String propertyName, final Object propertyValue,
  138.         final boolean beforeUpdate) {
  139.         super(source, type);
  140.         this.propertyName = propertyName;
  141.         this.propertyValue = propertyValue;
  142.         this.beforeUpdate = beforeUpdate;
  143.     }

  144.     /**
  145.      * Gets the name of the affected property. This can be <strong>null</strong> if no property change has lead to this event.
  146.      *
  147.      * @return the name of the property
  148.      */
  149.     public String getPropertyName() {
  150.         return propertyName;
  151.     }

  152.     /**
  153.      * Gets the value of the affected property if available.
  154.      *
  155.      * @return the value of the property; can be <strong>null</strong>
  156.      */
  157.     public Object getPropertyValue() {
  158.         return propertyValue;
  159.     }

  160.     /**
  161.      * Returns a flag if this event was generated before or after an update.
  162.      *
  163.      * @return <strong>true</strong> if this event was generated before an update; <strong>false</strong> otherwise
  164.      */
  165.     public boolean isBeforeUpdate() {
  166.         return beforeUpdate;
  167.     }
  168. }