Package org.apache.cayenne.event

## Class DefaultEventManager

- java.lang.Object
- - org.apache.cayenne.event.DefaultEventManager

- All Implemented Interfaces:
    `EventManager`

      public class DefaultEventManager
      extends Object
      implements EventManager

  A default implementation of `EventManager`.
  Since:
    3.1

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected List<org.apache.cayenne.event.DefaultEventManager.DispatchThread>` | `dispatchThreads` |
    `protected List<org.apache.cayenne.event.DefaultEventManager.Dispatch>` | `eventQueue` |
    `protected boolean` | `singleThread` |
    `protected boolean` | `stopped` |
    `protected Map<EventSubject,​org.apache.cayenne.event.DispatchQueue>` | `subjects` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultEventManager()` | Creates a multithreaded EventManager using default thread count.
    `DefaultEventManager​(int dispatchThreadCount)` | Creates an EventManager starting the specified number of threads for multithreaded dispatching.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject)` | Register an `EventListener` for events sent by any sender.
    `void` | `addListener​(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject, Object sender)` | Register an `EventListener` for events sent by a specific sender.
    `protected void` | `addListener​(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject, Object sender, boolean blocking)` |
    `void` | `addNonBlockingListener​(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject)` |
    `void` | `addNonBlockingListener​(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject, Object sender)` |
    `boolean` | `isSingleThreaded()` | Returns true if this EventManager is single-threaded.
    `boolean` | `isStopped()` | Returns true if the EventManager was stopped via `shutdown()` method.
    `void` | `postEvent​(EventObject event, EventSubject subject)` | Sends an event to all registered objects about a particular subject.
    `void` | `postNonBlockingEvent​(EventObject event, EventSubject subject)` | Sends an event to all registered objects about a particular subject.
    `boolean` | `removeAllListeners​(EventSubject subject)` | Removes all listeners for a given subject.
    `boolean` | `removeListener​(Object listener)` | Unregister the specified listener from all event subjects handled by this manager instance.
    `boolean` | `removeListener​(Object listener, EventSubject subject)` | Unregister the specified listener for the events about the given subject.
    `boolean` | `removeListener​(Object listener, EventSubject subject, Object sender)` | Unregister the specified listener for the events about the given subject and the given sender.
    `void` | `shutdown()` | Stops event threads.

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

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

- - ### Field Detail

    - #### subjects

          protected final Map<EventSubject,​org.apache.cayenne.event.DispatchQueue> subjects

    - #### eventQueue

          protected final List<org.apache.cayenne.event.DefaultEventManager.Dispatch> eventQueue

    - #### singleThread

          protected final boolean singleThread

    - #### dispatchThreads

          protected final List<org.apache.cayenne.event.DefaultEventManager.DispatchThread> dispatchThreads

    - #### stopped

          protected volatile boolean stopped

  - ### Constructor Detail

    - #### DefaultEventManager

          public DefaultEventManager()

      Creates a multithreaded EventManager using default thread count.

    - #### DefaultEventManager

          public DefaultEventManager​(int dispatchThreadCount)

      Creates an EventManager starting the specified number of threads for multithreaded dispatching. To create a single-threaded EventManager, use thread count of zero or less.

  - ### Method Detail

    - #### isStopped

          public boolean isStopped()

      Returns true if the EventManager was stopped via `shutdown()` method.
      Since:
        3.1

    - #### isSingleThreaded

          public boolean isSingleThreaded()

      Returns true if this EventManager is single-threaded. If so it will throw an exception on any attempt to register an unblocking listener or dispatch a non-blocking event.
      Specified by:
        `isSingleThreaded` in interface `EventManager`
      Since:
        1.2

    - #### shutdown

          @BeforeScopeEnd
          public void shutdown()

      Stops event threads. After the EventManager is stopped, it can not be restarted and should be discarded.
      Since:
        3.0

    - #### addListener

          public void addListener​(Object listener,
                                  String methodName,
                                  Class<?> eventParameterClass,
                                  EventSubject subject)

      Register an `EventListener` for events sent by any sender.
      Specified by:
        `addListener` in interface `EventManager`
      Throws:
        `RuntimeException` - if `methodName` is not found
      See Also:
        `addListener(Object, String, Class, EventSubject, Object)`

    - #### addNonBlockingListener

          public void addNonBlockingListener​(Object listener,
                                             String methodName,
                                             Class<?> eventParameterClass,
                                             EventSubject subject)

      Specified by:
        `addNonBlockingListener` in interface `EventManager`

    - #### addListener

          public void addListener​(Object listener,
                                  String methodName,
                                  Class<?> eventParameterClass,
                                  EventSubject subject,
                                  Object sender)

      Register an `EventListener` for events sent by a specific sender.
      Specified by:
        `addListener` in interface `EventManager`
      Parameters:
        `listener` - the object to be notified about events
        `methodName` - the name of the listener method to be invoked
        `eventParameterClass` - the class of the single event argument passed to `methodName`
        `subject` - the event subject that the listener is interested in
        `sender` - the object whose events the listener is interested in; `null` means 'any sender'.
      Throws:
        `RuntimeException` - if `methodName` is not found

    - #### addNonBlockingListener

          public void addNonBlockingListener​(Object listener,
                                             String methodName,
                                             Class<?> eventParameterClass,
                                             EventSubject subject,
                                             Object sender)

      Specified by:
        `addNonBlockingListener` in interface `EventManager`

    - #### addListener

          protected void addListener​(Object listener,
                                     String methodName,
                                     Class<?> eventParameterClass,
                                     EventSubject subject,
                                     Object sender,
                                     boolean blocking)

    - #### removeListener

          public boolean removeListener​(Object listener)

      Unregister the specified listener from all event subjects handled by this manager instance.
      Specified by:
        `removeListener` in interface `EventManager`
      Parameters:
        `listener` - the object to be unregistered
      Returns:
        `true` if `listener` could be removed for any existing subjects, else returns `false`.

    - #### removeAllListeners

          public boolean removeAllListeners​(EventSubject subject)

      Removes all listeners for a given subject.
      Specified by:
        `removeAllListeners` in interface `EventManager`

    - #### removeListener

          public boolean removeListener​(Object listener,
                                        EventSubject subject)

      Unregister the specified listener for the events about the given subject.
      Specified by:
        `removeListener` in interface `EventManager`
      Parameters:
        `listener` - the object to be unregistered
        `subject` - the subject from which the listener is to be unregistered
      Returns:
        `true` if `listener` could be removed for the given subject, else returns `false`.

    - #### removeListener

          public boolean removeListener​(Object listener,
                                        EventSubject subject,
                                        Object sender)

      Unregister the specified listener for the events about the given subject and the given sender.
      Specified by:
        `removeListener` in interface `EventManager`
      Parameters:
        `listener` - the object to be unregistered
        `subject` - the subject from which the listener is to be unregistered
        `sender` - the object whose events the listener was interested in; `null` means 'any sender'.
      Returns:
        `true` if `listener` could be removed for the given subject, else returns `false`.

    - #### postEvent

          public void postEvent​(EventObject event,
                                EventSubject subject)

      Sends an event to all registered objects about a particular subject. Event is sent synchronously, so the sender thread is blocked until all the listeners finish processing the event.
      Specified by:
        `postEvent` in interface `EventManager`
      Parameters:
        `event` - the event to be posted to the observers
        `subject` - the subject about which observers will be notified
      Throws:
        `IllegalArgumentException` - if event or subject are null

    - #### postNonBlockingEvent

          public void postNonBlockingEvent​(EventObject event,
                                           EventSubject subject)

      Sends an event to all registered objects about a particular subject. Event is queued by EventManager, releasing the sender thread, and is later dispatched in a separate thread.
      Specified by:
        `postNonBlockingEvent` in interface `EventManager`
      Parameters:
        `event` - the event to be posted to the observers
        `subject` - the subject about which observers will be notified
      Throws:
        `IllegalArgumentException` - if event or subject are null
      Since:
        1.1