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.

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