Package org.apache.commons.configuration2.event

## Class ConfigurationEvent

- java.lang.Object
- - java.util.EventObject
  - - org.apache.commons.configuration2.event.Event
    - - org.apache.commons.configuration2.event.ConfigurationEvent

- All Implemented Interfaces:
    `Serializable`

      public class ConfigurationEvent
      extends Event

  An event class for reporting updates on a configuration object.

  Event objects of this type are used for "raw" events, i.e. unfiltered modifications of any kind. A level with semantically higher events (e.g. for property changes) may be built on top of this fundamental event mechanism.

  Each event can contain the following data:

  - A source object, which is usually the configuration object that was modified.
  - The event's type. This is an object that corresponds to constant declarations in specific event classes. It describes what exactly has happened.
  - If available, the name of the property whose modification caused the event.
  - If available, the value of the property that caused this event.
  - A flag whether this event was generated before or after the update of the source configuration. A modification of a configuration typically causes two events: one event before and one event after the modification is performed. This allows event listeners to react at the correct point of time.

  The following standard events are generated by typical configuration implementations (the constants for the event types are defined in this class:

  ADD_PROPERTY
    This event is triggered for each call of the `addProperty()` method of a configuration object. It contains the name of the property, to which new data is added, and the value object that is added to this property (this may be an array or a list if multiple values are added).
  SET_PROPERTY
    Calling the `setProperty()` method triggers this event. The event object stores the name of the affected property and its new value.
  CLEAR_PROPERTY
    If a property is removed from a configuration (by calling the `clearProperty()` method), an event of this type is fired. In this case the event object only stores the name of the removed property, the value is null.
  CLEAR
    This event is fired when the whole configuration is cleared. The corresponding event object contains no additional data.
  Since:
    1.3
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static EventType<ConfigurationEvent>` | `ADD_NODES` | Constant for the event type for an add nodes operation.
    `static EventType<ConfigurationEvent>` | `ADD_PROPERTY` | Constant for the event type for an add property operation.
    `static EventType<ConfigurationEvent>` | `ANY` | Constant for the common super type of all configuration update events.
    `static EventType<ConfigurationEvent>` | `ANY_HIERARCHICAL` | Constant for the common base event type for all hierarchical update events.
    `static EventType<ConfigurationEvent>` | `CLEAR` | Constant for the event type for a clear operation.
    `static EventType<ConfigurationEvent>` | `CLEAR_PROPERTY` | Constant for the event type for a clear property operation.
    `static EventType<ConfigurationEvent>` | `CLEAR_TREE` | Constant for the event type for a clear tree operation.
    `static EventType<ConfigurationEvent>` | `SET_PROPERTY` | Constant for the event type for a set property operation.
    `static EventType<ConfigurationEvent>` | `SUBNODE_CHANGED` | Constant for the event type indicating a change on a sub configuration.

    - ### Fields inherited from class java.util.EventObject

      `source`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ConfigurationEvent​(Object source, EventType<? extends ConfigurationEvent> type, String propertyName, Object propertyValue, boolean beforeUpdate)` | Creates a new instance of `ConfigurationEvent` and initializes it.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `getPropertyName()` | Gets the name of the affected property.
    `Object` | `getPropertyValue()` | Gets the value of the affected property if available.
    `boolean` | `isBeforeUpdate()` | Returns a flag if this event was generated before or after an update.

    - ### Methods inherited from class org.apache.commons.configuration2.event.Event

      `appendPropertyRepresentation, getEventType, toString`

    - ### Methods inherited from class java.util.EventObject

      `getSource`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### ANY

          public static final EventType<ConfigurationEvent> ANY

      Constant for the common super type of all configuration update events.
      Since:
        2.0

    - #### ADD_PROPERTY

          public static final EventType<ConfigurationEvent> ADD_PROPERTY

      Constant for the event type for an add property operation.
      Since:
        2.0

    - #### SET_PROPERTY

          public static final EventType<ConfigurationEvent> SET_PROPERTY

      Constant for the event type for a set property operation.
      Since:
        2.0

    - #### CLEAR_PROPERTY

          public static final EventType<ConfigurationEvent> CLEAR_PROPERTY

      Constant for the event type for a clear property operation.
      Since:
        2.0

    - #### CLEAR

          public static final EventType<ConfigurationEvent> CLEAR

      Constant for the event type for a clear operation.
      Since:
        2.0

    - #### ANY_HIERARCHICAL

          public static final EventType<ConfigurationEvent> ANY_HIERARCHICAL

      Constant for the common base event type for all hierarchical update events. Events derived from this type are generated by some specific methods of hierarchical configurations.
      Since:
        2.0

    - #### ADD_NODES

          public static final EventType<ConfigurationEvent> ADD_NODES

      Constant for the event type for an add nodes operation.
      Since:
        2.0

    - #### CLEAR_TREE

          public static final EventType<ConfigurationEvent> CLEAR_TREE

      Constant for the event type for a clear tree operation.
      Since:
        2.0

    - #### SUBNODE_CHANGED

          public static final EventType<ConfigurationEvent> SUBNODE_CHANGED

      Constant for the event type indicating a change on a sub configuration.
      Since:
        2.0

  - ### Constructor Detail

    - #### ConfigurationEvent

          public ConfigurationEvent​(Object source,
                                    EventType<? extends ConfigurationEvent> type,
                                    String propertyName,
                                    Object propertyValue,
                                    boolean beforeUpdate)

      Creates a new instance of `ConfigurationEvent` and initializes it.
      Parameters:
        `source` - the event source
        `type` - the event's type
        `propertyName` - the name of the affected property
        `propertyValue` - the value of the affected property
        `beforeUpdate` - the before update flag

  - ### Method Detail

    - #### getPropertyName

          public String getPropertyName()

      Gets the name of the affected property. This can be null if no property change has lead to this event.
      Returns:
        the name of the property

    - #### getPropertyValue

          public Object getPropertyValue()

      Gets the value of the affected property if available.
      Returns:
        the value of the property; can be null

    - #### isBeforeUpdate

          public boolean isBeforeUpdate()

      Returns a flag if this event was generated before or after an update.
      Returns:
        true if this event was generated before an update; false otherwise