Package org.apache.commons.configuration2.event

# Class BaseEventSource

java.lang.Object
org.apache.commons.configuration2.event.BaseEventSource

All Implemented Interfaces:
  `EventSource`

Direct Known Subclasses:
  `AbstractConfiguration`

public class BaseEventSource extends Object implements EventSource

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. `BaseHierarchicalConfiguration` 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. They are handled via the regular `EventListener` interface, but there are special event types defined by `ConfigurationErrorEvent`. The `fireError()` method can be used by derived classes to send notifications about errors to registered observers.

Since:
  1.3

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BaseEventSource()`
  Creates a new instance of `BaseEventSource`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T extends Event>
  void`
  `addEventListener(EventType<T> eventType, EventListener<? super T> listener)`
  Adds an event listener for the specified event type.
  `void`
  `clearErrorListeners()`
  Removes all registered error listeners.
  `void`
  `clearEventListeners()`
  Removes all registered event listeners.
  `protected Object`
  `clone()`
  Overrides the `clone()` method to correctly handle so far registered event listeners.
  `void`
  `copyEventListeners(BaseEventSource source)`
  Copies all event listener registrations maintained by this object to the specified `BaseEventSource` object.
  `protected ConfigurationErrorEvent`
  `createErrorEvent(EventType<? extends ConfigurationErrorEvent> type, EventType<?> opType, String propName, Object propValue, Throwable ex)`
  Creates a `ConfigurationErrorEvent` object based on the passed in parameters.
  `protected <T extends ConfigurationEvent>
  ConfigurationEvent`
  `createEvent(EventType<T> type, String propName, Object propValue, boolean before)`
  Creates a `ConfigurationEvent` object based on the passed in parameters.
  `<T extends ConfigurationErrorEvent>
  void`
  `fireError(EventType<T> eventType, EventType<?> operationType, String propertyName, Object propertyValue, Throwable cause)`
  Creates an error event object and delivers it to all registered error listeners of a matching type.
  `protected <T extends ConfigurationEvent>
  void`
  `fireEvent(EventType<T> type, String propName, Object propValue, boolean before)`
  Creates an event object and delivers it to all registered event listeners.
  `List<EventListenerRegistrationData<?>>`
  `getEventListenerRegistrations()`
  Gets a list with all `EventListenerRegistrationData` objects currently contained for this event source.
  `<T extends Event>
  Collection<EventListener<? super T>>`
  `getEventListeners(EventType<T> eventType)`
  Gets a collection with all event listeners of the specified event type that are currently registered at this object.
  `boolean`
  `isDetailEvents()`
  Returns a flag whether detail events are enabled.
  `<T extends Event>
  boolean`
  `removeEventListener(EventType<T> eventType, EventListener<? super T> listener)`
  Removes the event listener registration for the given event type and listener.
  `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 Details

  - ### BaseEventSource

    public BaseEventSource()
    Creates a new instance of `BaseEventSource`.

- ## Method Details

  - ### addEventListener

    public <T extends Event> void addEventListener(EventType<T> eventType, EventListener<? super T> listener)
    Description copied from interface: `EventSource`
    Adds an event listener for the specified event type. This listener is notified about events of this type and all its sub types.
    Specified by:
      `addEventListener` in interface `EventSource`
    Type Parameters:
      `T` - the type of events processed by this listener
    Parameters:
      `eventType` - the event type (must not be null)
      `listener` - the listener to be registered (must not be null)

  - ### clearErrorListeners

    public void clearErrorListeners()
    Removes all registered error listeners.
    Since:
      1.4

  - ### clearEventListeners

    public void clearEventListeners()
    Removes all registered event listeners.

  - ### 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 `BaseEventSource` object will not be copied.
    Overrides:
      `clone` in class `Object`
    Returns:
      the cloned object
    Throws:
      `CloneNotSupportedException` - if the object's class does not support the `Cloneable` interface. Subclasses that override the `clone` method can also throw this exception to indicate that an instance cannot be cloned.
    Since:
      1.4

  - ### copyEventListeners

    public void copyEventListeners(BaseEventSource source)
    Copies all event listener registrations maintained by this object to the specified `BaseEventSource` object.
    Parameters:
      `source` - the target source for the copy operation (must not be null)
    Throws:
      `IllegalArgumentException` - if the target source is null
    Since:
      2.0

  - ### createErrorEvent

    protected ConfigurationErrorEvent createErrorEvent(EventType<? extends ConfigurationErrorEvent> type, EventType<?> opType, 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
      `opType` - the operation type related to this error
      `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

  - ### createEvent

    protected <T extends ConfigurationEvent> ConfigurationEvent createEvent(EventType<T> type, String propName, Object propValue, boolean before)
    Creates a `ConfigurationEvent` object based on the passed in parameters. This method is called by `fireEvent()` if it decides that an event needs to be generated.
    Type Parameters:
      `T` - the type of the event to be created
    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

    public <T extends ConfigurationErrorEvent> void fireError(EventType<T> eventType, EventType<?> operationType, String propertyName, Object propertyValue, Throwable cause)
    Creates an error event object and delivers it to all registered error listeners of a matching type.
    Type Parameters:
      `T` - the event type
    Parameters:
      `eventType` - the event's type
      `operationType` - the type of the failed operation
      `propertyName` - the name of the affected property (can be null)
      `propertyValue` - the value of the affected property (can be null)
      `cause` - the `Throwable` object that caused this error event

  - ### fireEvent

    protected <T extends ConfigurationEvent> void fireEvent(EventType<T> type, String propName, Object propValue, boolean before)
    Creates an event object and delivers it to all registered event listeners. The method checks first if sending an event is allowed (making use of the `detailEvents` property), and if listeners are registered.
    Type Parameters:
      `T` - the type of the event to be fired
    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

  - ### getEventListenerRegistrations

    public List<EventListenerRegistrationData<?>> getEventListenerRegistrations()
    Gets a list with all `EventListenerRegistrationData` objects currently contained for this event source. This method allows access to all registered event listeners, independent on their type.
    Returns:
      a list with information about all registered event listeners

  - ### getEventListeners

    public <T extends Event> Collection<EventListener<? super T>> getEventListeners(EventType<T> eventType)
    Gets a collection with all event listeners of the specified event type that are currently registered at this object.
    Type Parameters:
      `T` - the event type
    Parameters:
      `eventType` - the event type object
    Returns:
      a collection with the event listeners of the specified event type (this collection is a snapshot of the currently registered listeners; it cannot be manipulated)

  - ### isDetailEvents

    public boolean isDetailEvents()
    Returns a flag whether detail events are enabled.
    Returns:
      a flag if detail events are generated

  - ### removeEventListener

    public <T extends Event> boolean removeEventListener(EventType<T> eventType, EventListener<? super T> listener)
    Description copied from interface: `EventSource`
    Removes the event listener registration for the given event type and listener. An event listener instance may be registered multiple times for different event types. Therefore, when removing a listener the event type of the registration in question has to be specified. The return value indicates whether a registration was removed. A value of false means that no such combination of event type and listener was found.
    Specified by:
      `removeEventListener` in interface `EventSource`
    Type Parameters:
      `T` - the type of events processed by this listener
    Parameters:
      `eventType` - the event type
      `listener` - the event listener to be removed
    Returns:
      a flag whether a listener registration was removed

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