##### Configuration

- Home
- Download
- User's Guide
- Howtos (Release 1.2)
- Runtime Dependencies
- Building
- Roadmap
- Javadoc (Release 1.3)
- Javadoc (Release 1.2)
- Javadoc (Release 1.1)
- Javadoc (Release 1.0)
- SVN

##### Extensions

- Avalon Component

##### Project Documentation

- About
- Downloads
- Project Info
- Project Reports
- Development Process

##### Commons

- Home
- Components
- Sandbox
- Dormant
- Volunteering
- Contributing Patches
- Building Components
- Releasing Components
- Wiki

##### Legend

- External Link
- Opens in a new window

## Configuration Events

All configuration classes derived from `AbstractConfiguration` allow to register event listeners, which are notified whenever the configuration's data is changed. This provides an easy means for tracking updates on a configuration.

### Configuration listeners

Objects that are interested in update events triggered by configurations must implement the `ConfigurationListener` interface. This interface defines a single method `configurationChanged()`, which is passed a `ConfigurationEvent` object. The event object contains all information available about the modification, including:

- A source object, which is usually the configuration object that was modified.
- The event's type. This is a numeric value that corresponds to constant declarations in concrete configuration classes. It describes what exactly has happended.
- 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.

Depending on the event type not all of this data may be available.

For resolving the numeric event type use constants defined in `AbstractConfiguration` or derived classes. These constants start with the prefix `EVENT_` and have a speaking name. Here is an incomplete list of available event types with the configuration classes, in which they are defined:

AbstractConfiguration
  EVENT_ADD_PROPERTY (a property was added; the name of the affected property and the value that was added can be obtained from the event object), EVENT_SET_PROPERTY (a property's value was changed; the event object stores the name of the affected property and its new value), EVENT_CLEAR_PROPERTY (a property was removed from the configuration; its name is stored in the event object), EVENT_CLEAR (the configuration was cleared)
AbstractFileConfiguration
  EVENT_RELOAD (the configuration was reloaded)
HierarchicalConfiguration
  EVENT_ADD_NODES (the `addNodes()` method was called), EVENT_CLEAR_TREE (the `clearTree()` method was called)

### An example

Implementing an event listener is quite easy. As an example we are going to define an event listener, which logs all received configuration events to the console. The class could look as follows:

    import org.apache.commons.configuration.event.ConfigurationEvent;
    import org.apache.commons.configuration.event.ConfigurationListener;

    public class ConfigurationLogListener implements ConfigurationListener
    {
        public void configurationChanged(ConfigurationEvent event)
        {
            if (!event.isBeforeUpdate())
            {
                // only display events after the modification was done
                System.out.println("Received event!");
                System.out.println("Type = " + event.getType());
                if (event.getPropertyName() != null)
                {
                    System.out.println("Property name = " + event.getPropertyName());
                }
                if (event.getPropertyValue() != null)
                {
                    System.out.println("Property value = " + event.getPropertyValue());
                }
            }
        }
    }

Now an instance of this event listener class has to be registered at a configuration object:

    AbstractConfiguration config = ... // somehow create the configuration
    ConfigurationListener listener = new ConfigurationLogListener();
    config.addConfigurationListener(listener);
    ...
    config.addProperty("newProperty", "newValue"); // will fire an event