org.apache.commons.configuration2.event.ConfigurationEvent Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-configuration2 Show documentation
Tools to assist in the reading of configuration/preferences files in various formats
The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.configuration2.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 {@code 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 {@code 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 {@code 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
 */
public class ConfigurationEvent extends Event {
    /**
     * Constant for the common super type of all configuration update events.
     *
     * @since 2.0
     */
    public static final EventType ANY = new EventType<>(Event.ANY, "CONFIGURATION_UPDATE");

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

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

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

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

    /**
     * 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
     */
    public static final EventType ANY_HIERARCHICAL = new EventType<>(ANY, "HIERARCHICAL");

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

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

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

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

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

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

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

    /**
     * Creates a new instance of {@code ConfigurationEvent} and initializes it.
     *
     * @param source the event source
     * @param type the event's type
     * @param propertyName the name of the affected property
     * @param propertyValue the value of the affected property
     * @param beforeUpdate the before update flag
     */
    public ConfigurationEvent(final Object source, final EventType type, final String propertyName, final Object propertyValue,
        final boolean beforeUpdate) {
        super(source, type);
        this.propertyName = propertyName;
        this.propertyValue = propertyValue;
        this.beforeUpdate = beforeUpdate;
    }

    /**
     * Gets the name of the affected property. This can be null if no property change has lead to this event.
     *
     * @return the name of the property
     */
    public String getPropertyName() {
        return propertyName;
    }

    /**
     * Gets the value of the affected property if available.
     *
     * @return the value of the property; can be null
     */
    public Object getPropertyValue() {
        return propertyValue;
    }

    /**
     * Returns a flag if this event was generated before or after an update.
     *
     * @return true if this event was generated before an update; false otherwise
     */
    public boolean isBeforeUpdate() {
        return beforeUpdate;
    }
}