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 java.lang.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 and Description
protected class	EventEmitter.Filter

Constructor Summary

Constructors

Constructor and Description
EventEmitter()

Method Summary

Modifier and Type	Method and Description
protected abstract void	apply(Listener listener, Event event, java.lang.Object... args)
void	emit(Event event, java.lang.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 Detail

EventEmitter

public EventEmitter()

Method Detail

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,
                 java.lang.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,
                              java.lang.Object... args)