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 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.

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; the event object contains the key, to which the nodes were added, and a collection with the new nodes as value), EVENT_CLEAR_TREE (the clearTree() method was called; the event object stores the key of the removed sub tree), EVENT_SUBNODE_CHANGED (a SubnodeConfiguration that was created from this configuration has been changed. The value property of the event object contains the original event object as it was sent by the subnode configuration. Note: At the moment it is not possible to map the property key as it was received from the subnode configuration into the namespace of the parent configuration.)

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

Error listeners

Some implementations of the Configuration interface operate on underlying storages that can throw exceptions on each property access. As an example consider DatabaseConfiguration: this configuration class issues an SQL statement for each accessed property, which can potentially cause a SQLException.

In earlier versions of Commons Configuration such exceptions were simply logged and then swallowed. So for clients it was impossible to find out if something went wrong. From version 1.4 on there is a new way of dealing with those internal errors: the concept of error listeners.

A configuration error listener is very similar to a regular configuration event listener. Instead of the ConfigurationListener interface it has to implement the ConfigurationErrorListener interface, which defines a single method configurationError(). In case of an internal error this method is invoked, and a ConfigurationErrorEvent with information about that error is passed. By inheriting from ConfigurationEvent ConfigurationErrorEvent supports all information that is available for normal configuration listeners, too (e.g. the event type or the property that was accessed when the problem occurred; note that the isBefore() method does not really make sense for error events because an error can only occur after something was done, so it returns always false is this context). This data can be used to find out when and where the error happened. In addition there is the getCause() method that returns the Throwable object, which generated this event (i.e. the causing exception).

We can now continue our example from the previous section and make our example configuration listener also capable of tracing error events. To achieve this we let the ConfigurationLogListener class also implement the ConfigurationErrorListener interface:

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

public class ConfigurationLogListener
  implements ConfigurationListener, ConfigurationErrorListener
{
    public void configurationChanged(ConfigurationEvent event)
    {
      // remains unchanged, see above
      ...
    }

    public void configurationError(ConfigurationErrorEvent event)
    {
        System.out.println("An internal error occurred!");
        // Log the standard properties of the configuration event
        configurationChanged(event);
        // Now log the exception
        event.getCause().printStackTrace();
    }
}

Now the listener object has to be registered as an error listener, too. For this purpose AbstractConfiguration provides the addErrorListener() method. The following example fragment shows the registration of the log listener object:

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

Note: AbstractConfiguration already implements a mechanism for writing internal errors to a logger object: It has the protected addErrorLogListener() method that can be called by derived classes to register a listener that will output all occurring internal errors using the default logger. Configuration implementations like DatabaseConfiguration that are affected by potential internal errors call this method during their initialization. So the default behavior of Commons Configuration for these classes is not changed: they still catch occurring exceptions and log them. However by registering specific error listeners it is now possible for clients to implement their own handling of such errors.