org.apache.commons.configuration.event
Class EventSource

java.lang.Object
  extended by org.apache.commons.configuration.event.EventSource
Direct Known Subclasses:
AbstractConfiguration

public class EventSource
extends java.lang.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.

In addition to "normal" events, error events are supported. Such events signal an internal problem that occurred during access of properties. For them a special listener interface exists: ConfigurationErrorListener. There is another set of methods dealing with event listeners of this type. The fireError() method can be used by derived classes to send notifications about errors to registered observers.

Since:
1.3
Version:
$Id: EventSource.java 561230 2007-07-31 04:17:09Z rahul $
Author:
Commons Configuration team

Field Summary
private  int detailEvents
          A counter for the detail events.
private  java.util.Collection errorListeners
          A collection for the registered error listeners.
private  java.util.Collection listeners
          A collection for the registered event listeners.
 
Constructor Summary
EventSource()
          Creates a new instance of EventSource.
 
Method Summary
 void addConfigurationListener(ConfigurationListener l)
          Adds a configuration listener to this object.
 void addErrorListener(ConfigurationErrorListener l)
          Adds a new configuration error listener to this object.
 void clearConfigurationListeners()
          Removes all registered configuration listeners.
 void clearErrorListeners()
          Removes all registered error listeners.
protected  java.lang.Object clone()
          Overrides the clone() method to correctly handle so far registered event listeners.
protected  ConfigurationErrorEvent createErrorEvent(int type, java.lang.String propName, java.lang.Object propValue, java.lang.Throwable ex)
          Creates a ConfigurationErrorEvent object based on the passed in parameters.
protected  ConfigurationEvent createEvent(int type, java.lang.String propName, java.lang.Object propValue, boolean before)
          Creates a ConfigurationEvent object based on the passed in parameters.
private static void doAddListener(java.util.Collection listeners, java.lang.Object l)
          Adds a new listener object to a listener collection.
private static void doClearListeners(java.util.Collection listeners)
          Removes all entries from the given list of event listeners.
private static java.util.Collection doGetListeners(java.util.Collection listeners)
          Returns an unmodifiable snapshot of the given event listener collection.
private static boolean doRemoveListener(java.util.Collection listeners, java.lang.Object l)
          Removes an event listener from a listener collection.
protected  void fireError(int type, java.lang.String propName, java.lang.Object propValue, java.lang.Throwable ex)
          Creates an error event object and delivers it to all registered error listeners.
protected  void fireEvent(int type, java.lang.String propName, java.lang.Object propValue, boolean before)
          Creates an event object and delivers it to all registered event listeners.
 java.util.Collection getConfigurationListeners()
          Returns a collection with all configuration event listeners that are currently registered at this object.
 java.util.Collection getErrorListeners()
          Returns a collection with all configuration error listeners that are currently registered at this object.
private  void initListeners()
          Initializes the collections for storing registered event listeners.
 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.
 boolean removeErrorListener(ConfigurationErrorListener l)
          Removes the specified error 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
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

listeners

private java.util.Collection listeners
A collection for the registered event listeners.


errorListeners

private java.util.Collection errorListeners
A collection for the registered error listeners.


detailEvents

private int detailEvents
A counter for the detail events.

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 java.util.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 is a snapshot of the currently registered listeners; manipulating it has no effect on this event source object)

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

addErrorListener

public void addErrorListener(ConfigurationErrorListener l)
Adds a new configuration error listener to this object. This listener will then be notified about internal problems.

Parameters:
l - the listener to register (must not be null)
Since:
1.4

removeErrorListener

public boolean removeErrorListener(ConfigurationErrorListener l)
Removes the specified error listener so that it does not receive any further events caused by this object.

Parameters:
l - the listener to remove
Returns:
a flag whether the listener could be found and removed
Since:
1.4

clearErrorListeners

public void clearErrorListeners()
Removes all registered error listeners.

Since:
1.4

getErrorListeners

public java.util.Collection getErrorListeners()
Returns a collection with all configuration error listeners that are currently registered at this object.

Returns:
a collection with the registered ConfigurationErrorListeners (this collection is a snapshot of the currently registered listeners; it cannot be manipulated)
Since:
1.4

fireEvent

protected void fireEvent(int type,
                         java.lang.String propName,
                         java.lang.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,
                                         java.lang.String propName,
                                         java.lang.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

fireError

protected void fireError(int type,
                         java.lang.String propName,
                         java.lang.Object propValue,
                         java.lang.Throwable ex)
Creates an error event object and delivers it to all registered error listeners.

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)
ex - the Throwable object that caused this error event
Since:
1.4

createErrorEvent

protected ConfigurationErrorEvent createErrorEvent(int type,
                                                   java.lang.String propName,
                                                   java.lang.Object propValue,
                                                   java.lang.Throwable ex)
Creates a ConfigurationErrorEvent object based on the passed in parameters. This is called by fireError() 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)
ex - the Throwable object that caused this error event
Returns:
the event object
Since:
1.4

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException
Overrides the clone() method to correctly handle so far registered event listeners. This implementation ensures that the clone will have empty event listener lists, i.e. the listeners registered at an EventSource object will not be copied.

Overrides:
clone in class java.lang.Object
Returns:
the cloned object
Throws:
java.lang.CloneNotSupportedException - if cloning is not allowed
Since:
1.4

doAddListener

private static void doAddListener(java.util.Collection listeners,
                                  java.lang.Object l)
Adds a new listener object to a listener collection. This is done in a synchronized block. The listener must not be null.

Parameters:
listeners - the collection with the listeners
l - the listener object

doRemoveListener

private static boolean doRemoveListener(java.util.Collection listeners,
                                        java.lang.Object l)
Removes an event listener from a listener collection. This is done in a synchronized block.

Parameters:
listeners - the collection with the listeners
l - the listener object
Returns:
a flag whether the listener could be found and removed

doClearListeners

private static void doClearListeners(java.util.Collection listeners)
Removes all entries from the given list of event listeners.

Parameters:
listeners - the collection with the listeners

doGetListeners

private static java.util.Collection doGetListeners(java.util.Collection listeners)
Returns an unmodifiable snapshot of the given event listener collection.

Parameters:
listeners - the collection with the listeners
Returns:
a snapshot of the listeners collection

initListeners

private void initListeners()
Initializes the collections for storing registered event listeners.