com.brightcove.player.event

## Class RegisteringEventEmitter

- java.lang.Object
- - com.brightcove.player.event.RegisteringEventEmitter

- All Implemented Interfaces:
    EventEmitter

      public class RegisteringEventEmitter
      extends java.lang.Object
      implements EventEmitter

  The RegisteringEventEmitter allows developers to constrain which events their Components are intended to listen for and emit. If a component attempts to emit or listen for an event that it hasn't explicitly listed, an exception will be thrown.

  Registration occurs by creating a new instance of RegisteringEventEmitter, using a shared EventEmitter (typically EventEmitterImpl), and the class to be registered. The class in question MUST be decorated with two annotations: ListensFor and Emits. Each takes a String[], populated with EventType strings, attached to their 'events' property. Each annotation MUST be included, even if the component has no intention of listening or emitting any events.

  For example, the following component class declartion:

  @Emits(events = {EventType.PLAY, EventType.STOP})
  @ListensFor(events = {EventType.PLAY})
  public class SampleComponent implements Component

  See Also:
    `EventEmitter`, `EventEmitterImpl`, `Component`, `Emits`, `ListensFor`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `RegisteringEventEmitter(EventEmitter emitter, java.lang.Class<? extends Component> component)` Main constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static RegisteringEventEmitter` | `build(EventEmitter incomingEmitter, java.lang.Class<? extends Component> componentClass)` Factory method to create a new RegisteringEventEmitter given an existing EventEmitter and a Component implementation.
    `protected java.util.List<java.lang.String>` | `convertEventsFromAnnotation(java.lang.Class<? extends Component> componentClass, java.lang.Class<? extends java.lang.annotation.Annotation> annotationClass)` Convenience method on BaseComponent which converts the eventTypes in the ListensFor or Emits annotations to a List of event names for ease of use.
    `void` | `disable()` Disables listener registration and event emitting.
    `void` | `emit(java.lang.String eventType)` Emits an Event of EventType.
    `void` | `emit(java.lang.String eventType, java.util.Map<java.lang.String,java.lang.Object> properties)` Emits and Event of EventType, provided the Component is allowed to do so.
    `void` | `enable()` Enables listener registration and event emitting.
    `java.util.List<java.lang.String>` | `getAllowedEmittedEvents()` Retrieves a list of all Events that are allowed to be emitted in this RegisteringEventEmitter.
    `java.util.List<java.lang.String>` | `getAllowedListenEvents()` Retrieves a list of all Events that are allowed to be listened in this RegisteringEventEmitter.
    `EventEmitter` | `getRootEmitter()` Retrieve the underlying EventEmitter provided when initializing this emitter.
    `void` | `off()` Remove all listeners.
    `void` | `off(java.lang.String eventType, int token)` Remove a listener from handling an event of EventType.
    `int` | `on(java.lang.String eventType, EventListener listener)` Add a listener for an EventType, filtered by what the component is allowed to listen for.
    `int` | `once(java.lang.String eventType, EventListener listener)` Add a listener for an EventType, filtered by what the component is allowed to listen for.
    `void` | `request(java.lang.String eventType, EventListener listener)` Requests a response from the first listener to respond.
    `void` | `request(java.lang.String eventType, java.util.Map<java.lang.String,java.lang.Object> properties, EventListener listener)` Requests a response from the first listener to respond.
    `void` | `respond(Event event)` Respond to a request.
    `void` | `respond(java.util.Map<java.lang.String,java.lang.Object> properties)` Respond to a request.

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

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

- - ### Constructor Detail

    - #### RegisteringEventEmitter

          public RegisteringEventEmitter(EventEmitter emitter,
                                         java.lang.Class<? extends Component> component)
                                  throws java.lang.IllegalArgumentException

      Main constructor. Requires both an emitter and component. Will throw an IllegalArgumentException if either is missing.
      Parameters:
        `emitter` -
        `component` -
      Throws:
        `java.lang.IllegalArgumentException`

  - ### Method Detail

    - #### getAllowedEmittedEvents

          public java.util.List<java.lang.String> getAllowedEmittedEvents()

      Retrieves a list of all Events that are allowed to be emitted in this RegisteringEventEmitter.
      Returns:
        a List of EventType strings for all allowed emits

    - #### getAllowedListenEvents

          public java.util.List<java.lang.String> getAllowedListenEvents()

      Retrieves a list of all Events that are allowed to be listened in this RegisteringEventEmitter.
      Returns:
        a List of EventType strings for all allowed listened events

    - #### on

          public int on(java.lang.String eventType,
                        EventListener listener)

      Add a listener for an EventType, filtered by what the component is allowed to listen for. The response token should be cached by component for use later in the component lifecycle
      Specified by:
        `on` in interface `EventEmitter`
      Parameters:
        `eventType` -
        `listener` -
      Returns:
        an empty string if listener was not attached, a UUID in string form if was successfully attached
      See Also:
        `EventListener`

    - #### once

          public int once(java.lang.String eventType,
                          EventListener listener)

      Add a listener for an EventType, filtered by what the component is allowed to listen for. This listener will be handled only once, at which point it is removed. The response token should be cached by component for use later in the component lifecycle
      Specified by:
        `once` in interface `EventEmitter`
      Parameters:
        `eventType` -
        `listener` -
      Returns:
        an empty string if listener was not attached, a UUID in string form if was successfully attached
      See Also:
        `EventListener`

    - #### off

          public void off()

      Remove all listeners.
      Specified by:
        `off` in interface `EventEmitter`

    - #### off

          public void off(java.lang.String eventType,
                          int token)

      Remove a listener from handling an event of EventType. Requires a token given by on() or once()
      Specified by:
        `off` in interface `EventEmitter`
      Parameters:
        `eventType` -
        `token` -

    - #### emit

          public void emit(java.lang.String eventType)

      Emits an Event of EventType. However, the Event will only be emitted if the component is allowed to do so
      Specified by:
        `emit` in interface `EventEmitter`
      Parameters:
        `eventType` -

    - #### emit

          public void emit(java.lang.String eventType,
                           java.util.Map<java.lang.String,java.lang.Object> properties)

      Emits and Event of EventType, provided the Component is allowed to do so. Will also pass along a set of String properties.
      Specified by:
        `emit` in interface `EventEmitter`
      Parameters:
        `eventType` -
        `properties` -

    - #### getRootEmitter

          public EventEmitter getRootEmitter()

      Retrieve the underlying EventEmitter provided when initializing this emitter.
      Returns:
        the root EventEmitter

    - #### build

          public static RegisteringEventEmitter build(EventEmitter incomingEmitter,
                                                      java.lang.Class<? extends Component> componentClass)

      Factory method to create a new RegisteringEventEmitter given an existing EventEmitter and a Component implementation. All RegisteringEventEmitters should be created with this method.
      Parameters:
        `incomingEmitter` - an existing EventEmitter, could also be a RegisteringEventEmitter
        `componentClass` - the Component implementation to be managed by this emitter
      Returns:
        a properly initialized RegisteringEventEmitter

    - #### request

          public void request(java.lang.String eventType,
                              EventListener listener)

      Requests a response from the first listener to respond. The response is handled by the provided listener, after which the listener is removed.
      Specified by:
        `request` in interface `EventEmitter`
      Parameters:
        `eventType` - The type of Event to emit and expect a response from
        `listener` - A listener to process the response. After processing, the response should be removed
      See Also:
        `EventListener`, `EventType`

    - #### request

          public void request(java.lang.String eventType,
                              java.util.Map<java.lang.String,java.lang.Object> properties,
                              EventListener listener)

      Requests a response from the first listener to respond. The response is handled by the provided listener, after which the listener is removed. The provided properties map is passed on to the responding listener
      Specified by:
        `request` in interface `EventEmitter`
      Parameters:
        `eventType` - The type of Event to emit and expect a response from
        `properties` - A Map of properties to pass along the event chain
        `listener` - A listener to process the response. After processing, the response should be removed
      See Also:
        `EventListener`, `EventType`

    - #### respond

          public void respond(java.util.Map<java.lang.String,java.lang.Object> properties)

      Respond to a request. Should be placed within an EventListener and via some means (e.g. the token of an InvocationContainer) know which Request Listener to respond to. See
      Specified by:
        `respond` in interface `EventEmitter`
      Parameters:
        `properties` -

    - #### respond

          public void respond(Event event)

      Respond to a request. Should be called within an EventListener and given an Event object with the appropriate REQUEST_TOKEN value
      Specified by:
        `respond` in interface `EventEmitter`
      Parameters:
        `event` - an Event object with, at minimum, the necessary REQUEST_TOKEN value

    - #### enable

          public void enable()

      Enables listener registration and event emitting.
      Specified by:
        `enable` in interface `EventEmitter`

    - #### disable

          public void disable()

      Disables listener registration and event emitting.
      Specified by:
        `disable` in interface `EventEmitter`

    - #### convertEventsFromAnnotation

          protected java.util.List<java.lang.String> convertEventsFromAnnotation(java.lang.Class<? extends Component> componentClass,
                                                                                 java.lang.Class<? extends java.lang.annotation.Annotation> annotationClass)

      Convenience method on BaseComponent which converts the eventTypes in the ListensFor or Emits annotations to a List of event names for ease of use.
      Parameters:
        `componentClass` - The component's class.
        `annotationClass` - The annotation's class.
      Returns:
        A list of event names.