## 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 mechanism. 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 1234617 2012-01-22 21:31:01Z 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` `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 Object` `clone()` Overrides the `clone()` method to correctly handle so far registered event listeners.
`protected ConfigurationErrorEvent` `createErrorEvent(int type, String propName, Object propValue, Throwable ex)` Creates a `ConfigurationErrorEvent` object based on the passed in parameters.
`protected ConfigurationEvent` `createEvent(int type, String propName, Object propValue, boolean before)` Creates a `ConfigurationEvent` object based on the passed in parameters.
`protected void` `fireError(int type, String propName, Object propValue, Throwable ex)` Creates an error event object and delivers it to all registered error listeners.
`protected void` `fireEvent(int type, String propName, Object propValue, boolean before)` Creates an event object and delivers it to all registered event listeners.
`Collection<ConfigurationListener>` `getConfigurationListeners()` Returns a collection with all configuration event listeners that are currently registered at this object.
`Collection<ConfigurationErrorListener>` `getErrorListeners()` Returns a collection with all configuration error 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.
`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`

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<ConfigurationListener> getConfigurationListeners()

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

  Returns:
    a collection with the registered `ConfigurationListener`s (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 Collection<ConfigurationErrorListener> getErrorListeners()

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

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

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

### fireError

    protected void fireError(int type,
                             String propName,
                             Object propValue,
                             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,
                                                       String propName,
                                                       Object propValue,
                                                       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 Object clone()
                    throws 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 `Object`
  Returns:
    the cloned object
  Throws:
    `CloneNotSupportedException` - if cloning is not allowed
  Since:
    1.4

Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.