Package com.norconex.commons.lang.event

# Class EventManager

java.lang.Object
com.norconex.commons.lang.event.EventManager

public class EventManager extends Object

Manages event listeners and logs events. New event managers can be constructed with a "parent" event manager. When chained as such, event on a particular event manager are bubbled up to the parents but never down to children. Events are logged by the manager in the chain that first fires the event.

When an event holds an exception, a summarized version of it is logged by default. To have the full stack trace logged by this event manager, set the log level for the corresponding class to `DEBUG` (or more verbose).

Since:
  2.0.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EventManager()`
  `EventManager(EventManager parentEventManager)`
  Wraps a parent event manager.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListener(EventListener<Event> listener)`
  Adds an event listener.
  `void`
  `addListeners(Collection<EventListener<Event>> listeners)`
  Adds event listeners.
  `void`
  `addListenersFromScan(Object obj)`
  Adds listeners found in an object graph.
  `void`
  `bindParent(EventManager parentEventManager)`
  `void`
  `clearListeners()`
  Clears all previously added listeners.
  `void`
  `fire(Event event)`
  `void`
  `fire(Event event, Level level)`
  `int`
  `getListenerCount()`
  Gets the number of event listeners registered with this event manager.
  `List<EventListener<Event>>`
  `getListeners()`
  Returns an unmodifiable list of event listeners in this event manager.
  `void`
  `log(Event event, Level level)`
  `boolean`
  `removeListener(EventListener<Event> listener)`
  Removes a listener instance.
  `boolean`
  `removeListeners(Collection<EventListener<Event>> listeners)`
  Removes listener instances.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### EventManager

    public EventManager()

  - ### EventManager

    public EventManager(EventManager parentEventManager)
    Wraps a parent event manager. Events fired on this event manager will be fired on this instance listeners first, then its parent listeners. Modifying the list of listeners in this instance does not impact listeners of the parent event manager.
    Parameters:
      `parentEventManager` - parent event manager

- ## Method Details

  - ### addListener

    public void addListener(EventListener<Event> listener)
    Adds an event listener. Event listeners are added by "identity", meaning you can have multiple listeners coexisting even if their test for equality returns `true`. Adding a `null` event listener has no effect.
    Parameters:
      `listener` - an event listener

  - ### addListeners

    public void addListeners(Collection<EventListener<Event>> listeners)
    Adds event listeners. Event listeners are added by "identity", meaning you can have multiple listeners coexisting even if their test for equality returns `true`. Adding a `null` collection has no effect.
    Parameters:
      `listeners` - event listeners

  - ### addListenersFromScan

    public void addListenersFromScan(Object obj)
    Adds listeners found in an object graph. Recursively queries the object bean properties for non `null` objects implementing `EventListener`.
    Parameters:
      `obj` - the object to retrive listeners from

  - ### getListeners

    public List<EventListener<Event>> getListeners()
    Returns an unmodifiable list of event listeners in this event manager.
    Returns:
      list of listeners

  - ### removeListener

    public boolean removeListener(EventListener<Event> listener)
    Removes a listener instance. Removal is done by "identity", meaning you can have listeners that are not removed despite testing `true` for equality. Removing a `null` listener has no effect.
    Parameters:
      `listener` - the listener instance to remove
    Returns:
      `true` if a matching instance was removed

  - ### removeListeners

    public boolean removeListeners(Collection<EventListener<Event>> listeners)
    Removes listener instances. Removal is done by "identity", meaning you can have listeners that are not removed despite testing `true` for equality. Removing a `null` collection has no effect.
    Parameters:
      `listeners` - listener instances to remove
    Returns:
      `true` if one or more listeners were removed

  - ### clearListeners

    public void clearListeners()
    Clears all previously added listeners. Does not affect listeners associated with a parent event manager.

  - ### getListenerCount

    public int getListenerCount()
    Gets the number of event listeners registered with this event manager. Listeners attached to a parent are not counted.
    Returns:
      listener count

  - ### fire

    public void fire(Event event)

  - ### fire

    public void fire(Event event, Level level)

  - ### bindParent

    public void bindParent(EventManager parentEventManager)

  - ### log

    public void log(Event event, Level level)