Package io.ably.lib.util

Class EventEmitter<Event,Listener>

java.lang.Object
io.ably.lib.util.EventEmitter<Event,Listener>
Type Parameters:
Event - an Enum containing the event names that listeners may be registered for
Listener - the interface type of the listener
Direct Known Subclasses:
ChannelBase, Connection
public abstract class EventEmitter<Event,Listener> extends Object
A generic interface for event registration and delivery used in a number of the types in the Realtime client library. For example, the Connection object emits events for connection state using the EventEmitter pattern.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected class 
    EventEmitter.Filter
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    EventEmitter()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract void
    apply(Listener listener, Event event, Object... args)
     
    void
    emit(Event event, Object... args)
    Emits an event, calling registered listeners with the given event name and any other given arguments.
    void
    off()
    Deregisters all registrations, for all events and listeners.
    void
    off(Event event, Listener listener)
    Removes all registrations that match both the specified listener and the specified event.
    void
    off(Listener listener)
    Deregisters the specified listener.
    void
    on(Event event, Listener listener)
    Registers the provided listener for the specified event.
    void
    on(Listener listener)
    Registers the provided listener all events.
    void
    once(Event event, Listener listener)
    Registers the provided listener for the first occurrence of a single named event specified as the Event argument.
    void
    once(Listener listener)
    Registers the provided listener for the first event that is emitted.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • EventEmitter

      public EventEmitter()

  • Method Details

    • off

      public void off()
      Deregisters all registrations, for all events and listeners.

      Spec: RTE5

    • on

      public void on(Listener listener)
      Registers the provided listener all events. If on() is called more than once with the same listener, the listener is only added once. Note: This is in deviation from the spec (see below).

      Spec: RTE4

      Parameters:
      listener - The event listener.

      This listener is invoked on a background thread.

    • once

      public void once(Listener listener)
      Registers the provided listener for the first event that is emitted. If once() is called more than once with the same listener, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using once(), and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted would not invoke the listener as once() ensures that each registration is only invoked once.

      Spec: RTE4

      Parameters:
      listener - The event listener.

      This listener is invoked on a background thread.

    • off

      public void off(Listener listener)
      Deregisters the specified listener. Removes all registrations matching the given listener, regardless of whether they are associated with an event or not.

      Spec: RTE5

      Parameters:
      listener - The event listener.

    • on

      public void on(Event event, Listener listener)
      Registers the provided listener for the specified event. If on() is called more than once with the same listener, even with a different event, the original listener is replaced. Note: This is in deviation from the spec (see below).

      Spec: RTE4

      Parameters:
      event - The named event to listen for.
      listener - The event listener.

      This listener is invoked on a background thread.

    • once

      public void once(Event event, Listener listener)
      Registers the provided listener for the first occurrence of a single named event specified as the Event argument. If once() is called more than once with the same listener, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using once(), and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted would not invoke the listener as once() ensures that each registration is only invoked once.

      Spec: RTE4

      Parameters:
      listener - The event listener.
      event - The named event to listen for.

      This listener is invoked on a background thread.

    • off

      public void off(Event event, Listener listener)
      Removes all registrations that match both the specified listener and the specified event.

      Spec: RTE5

      Parameters:
      listener - The event listener.
      event - The named event.

    • emit

      public void emit(Event event, Object... args)
      Emits an event, calling registered listeners with the given event name and any other given arguments. If an exception is raised in any of the listeners, the exception is caught by the EventEmitter and the exception is logged to the Ably logger.

      Spec: RTE5

      Parameters:
      event - The named event.
      args - the arguments to pass to listeners

    • apply

      protected abstract void apply(Listener listener, Event event, Object... args)