org.apache.commons.configuration.event
Class EventSource

java.lang.Object
  org.apache.commons.configuration.event.EventSource

Direct Known Subclasses:

AbstractConfiguration

public class EventSource

extends Object

A base class for objects that can generate configuration events.

This class implements functionality for managing a set of event listeners that can be notified when an event occurs. It can be extended by configuration classes that support the event machanism. In this case these classes only need to call the fireEvent() method when an event is to be delivered to the registered listeners.

Adding and removing event listeners can happen concurrently to manipulations on a configuration that cause events. The operations are synchronized.

With the detailEvents property the number of detail events can be controlled. Some methods in configuration classes are implemented in a way that they call other methods that can generate their own events. One example is the setProperty() method that can be implemented as a combination of clearProperty() and addProperty(). With detailEvents set to true, all involved methods will generate events (i.e. listeners will receive property set events, property clear events, and property add events). If this mode is turned off (which is the default), detail events are suppressed, so only property set events will be received. Note that the number of received detail events may differ for different configuration implementations. HierarchicalConfiguration for instance has a custom implementation of setProperty(), which does not generate any detail events.

Since:

1.3

Version:

$Id: EventSource.java 439648 2006-09-02 20:42:10Z oheger $

Author:

Commons Configuration team

Constructor Summary

EventSource()
Creates a new instance of EventSource.

Method Summary

void	addConfigurationListener(ConfigurationListener l) Adds a configuration listener to this object.
void	clearConfigurationListeners() Removes all registered configuration listeners.
protected ConfigurationEvent	createEvent(int type, String propName, Object propValue, boolean before) Creates a ConfigurationEvent object based on the passed in parameters.
protected void	fireEvent(int type, String propName, Object propValue, boolean before) Creates an event object and delivers it to all registered event listeners.
Collection	getConfigurationListeners() Returns a collection with all configuration event listeners that are currently registered at this object.
boolean	isDetailEvents() Returns a flag whether detail events are enabled.
boolean	removeConfigurationListener(ConfigurationListener l) Removes the specified event listener so that it does not receive any further events caused by this object.
void	setDetailEvents(boolean enable) Determines whether detail events should be generated.

Methods inherited from class java.lang.Object

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

Constructor Detail

EventSource

public EventSource()

Creates a new instance of EventSource.

Method Detail

addConfigurationListener

public void addConfigurationListener(ConfigurationListener l)

Adds a configuration listener to this object.

Parameters:

l - the listener to add

removeConfigurationListener

public boolean removeConfigurationListener(ConfigurationListener l)

Removes the specified event listener so that it does not receive any further events caused by this object.

Parameters:

l - the listener to be removed

Returns:

a flag whether the event listener was found

getConfigurationListeners

public Collection getConfigurationListeners()

Returns a collection with all configuration event listeners that are currently registered at this object.

Returns:

a collection with the registered ConfigurationListeners (this collection cannot be changed)

clearConfigurationListeners

public void clearConfigurationListeners()

Removes all registered configuration listeners.

isDetailEvents

public boolean isDetailEvents()

Returns a flag whether detail events are enabled.

Returns:

a flag if detail events are generated

setDetailEvents

public void setDetailEvents(boolean enable)

Determines whether detail events should be generated. If enabled, some methods can generate multiple update events. Note that this method records the number of calls, i.e. if for instance setDetailEvents(false) was called three times, you will have to invoke the method as often to enable the details.

Parameters:

enable - a flag if detail events should be enabled or disabled

fireEvent

protected void fireEvent(int type,
                         String propName,
                         Object propValue,
                         boolean before)

Creates an event object and delivers it to all registered event listeners. The method will check first if sending an event is allowed (making use of the detailEvents property), and if listeners are registered.

Parameters:

type - the event's type

propName - the name of the affected property (can be null)

propValue - the value of the affected property (can be null)

before - the before update flag

createEvent

protected ConfigurationEvent createEvent(int type,
                                         String propName,
                                         Object propValue,
                                         boolean before)

Creates a ConfigurationEvent object based on the passed in parameters. This is called by fireEvent() if it decides that an event needs to be generated.

Parameters:

type - the event's type

propName - the name of the affected property (can be null)

propValue - the value of the affected property (can be null)

before - the before update flag

Returns:

the newly created event object