Package org.omegazero.common.event

Class EventEmitter

java.lang.Object

org.omegazero.common.event.EventEmitter

public class EventEmitter
extends Object

Used for distributing and executing events among a set of registered listeners.

Listeners are added to a specific event name using addEventListener(String, GenericRunnable) or similar methods. Upon dispatching an event using runEvent(String, Object...), all event listeners registered for the given event name are called with the given arguments. The number of arguments passed and the number of arguments in the event listeners must match, otherwise an IllegalArgumentException will be thrown at the listener-level.

Each event may also have a default listener registered, which is called when the event is emitted, and only if no other (regular) listeners are registered (see setDefaultEventListener(String, GenericRunnable)).

By default, all event listeners are executed regardless of any exceptions thrown at the listener-level. If any listener did throw an exception, the runEvent call will throw an ExecutionFailedException detailing the thrown exception(s), after all listeners were executed. See also: setCoalesceListenerErrors(boolean).

A call to createEventId(String, int) will switch this EventEmitter to fastAccess mode, which may be used for more efficient event dispatching. In this mode, all event names must be registered with a call to this method.

This class is thread-safe.

Since:

2.10

API Note:

The behavior and API naming of this class is heavily inspired by the similar Node.js events API

Constructor Summary

Constructors

Constructor	Description
EventEmitter()

Method Summary

Modifier and Type	Method	Description
void	addEventListener(String name, GenericRunnable runnable)	Registers the given event listener for the given event name.
void	addEventListenerOnce(String name, GenericRunnable runnable)	Registers the given event listener for the given event name.
int	createEventId(String name)	Creates an ID for the given event name used for more efficient event dispatching.
int	createEventId(String name, int expect)	Creates an ID for the given event name used for more efficient event dispatching.
final int	emit(int id, Object... args)	Alias for runEvent(int, Object...).
final int	emit(String name, Object... args)	Alias for runEvent(String, Object...).
GenericRunnable	getDefaultEventListener(String name)	Returns the default event listener of the given event name.
int	getEventListenerCount(String name)	Returns the number of event listeners registered for the given event name, excluding the default listener.
List<GenericRunnable>	getEventListeners(String name)	Returns an unmodifiable, possibly empty, list of the event listeners registered for the given event name, excluding the default listener.
Set<String>	getEventNames()	Returns an unmodifiable set of known event names.
boolean	isEventRegistered(String name)	Returns true if the given event name is a known event.
final EventEmitter	off(String name, GenericRunnable runnable)	Alias for removeEventListener(String, GenericRunnable).
final EventEmitter	on(String name, GenericRunnable runnable)	Alias for addEventListener(String, GenericRunnable).
final EventEmitter	on(String name, GenericRunnable.A0 runnable)	Alias for addEventListener(String, GenericRunnable) for zero-argument events.
final EventEmitter	on(String name, GenericRunnable.A1<?> runnable)	Alias for addEventListener(String, GenericRunnable) for single-argument events.
final EventEmitter	on(String name, GenericRunnable.A2<?,?> runnable)	Alias for addEventListener(String, GenericRunnable) for two-argument events.
final EventEmitter	on(String name, GenericRunnable.A3<?,?,?> runnable)	Alias for addEventListener(String, GenericRunnable) for three-argument events.
final EventEmitter	on(String name, GenericRunnable.A4<?,?,?,?> runnable)	Alias for addEventListener(String, GenericRunnable) for four-argument events.
final EventEmitter	once(String name, GenericRunnable runnable)	Alias for addEventListenerOnce(String, GenericRunnable).
final EventEmitter	once(String name, GenericRunnable.A0 runnable)	Alias for addEventListenerOnce(String, GenericRunnable) for zero-argument events.
final EventEmitter	once(String name, GenericRunnable.A1<?> runnable)	Alias for addEventListenerOnce(String, GenericRunnable) for single-argument events.
final EventEmitter	once(String name, GenericRunnable.A2<?,?> runnable)	Alias for addEventListenerOnce(String, GenericRunnable) for two-argument events.
final EventEmitter	once(String name, GenericRunnable.A3<?,?,?> runnable)	Alias for addEventListenerOnce(String, GenericRunnable) for three-argument events.
final EventEmitter	once(String name, GenericRunnable.A4<?,?,?,?> runnable)	Alias for addEventListenerOnce(String, GenericRunnable) for four-argument events.
void	prependEventListener(String name, GenericRunnable runnable)	Registers the given event listener for the given event name.
void	removeAllEventListeners(String name)	Removes all event listeners from the event with the given name, including the default listener.
void	removeDefaultEventListener(String name)	Removes the default event listener of the given event name.
void	removeEventListener(String name, GenericRunnable runnable)	Removes the given event listener from the event with the given name.
void	reserveEventIdSpace(int highestId)	Pre-allocates internal data structures for storing event IDs up to highestId.
int	runEvent(int id, Object... args)	Dispatches an event with the given fastAccess event ID.
int	runEvent(String name, Object... args)	Dispatches an event with the given name.
void	setCoalesceListenerErrors(boolean coalesceListenerErrors)	If set to true, all listeners for an event will always be executed regardless of errors thrown at the listener-level.
void	setDefaultEventListener(String name, GenericRunnable runnable)	Registers the default event listener for the given event name.

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

createEventId

public int createEventId(String name)

Creates an ID for the given event name used for more efficient event dispatching.

Equivalent to a call to:

        createEventId(name, -1)
 

Parameters:

name - The event name

Returns:

The EventEmitter-scope unique event ID

createEventId

public int createEventId(String name,
 int expect)

Creates an ID for the given event name used for more efficient event dispatching.

Calling this method switches this EventEmitter to fastAccess mode.

If expect is non-negative and the generated next event ID does not match its value, no event ID will be created and an IllegalStateException thrown. This may be used by applications to assert a specific event ID, which removes the requirement for runtime event ID storage. Event IDs always start at 0 for the first event and are incremented for each additional event.

Parameters:

name - The event name

expect - The expected event ID

Returns:

The EventEmitter-scope unique event ID, same as expect if non-negative

Throws:

IllegalStateException - If expect is non-negative and does not match the next event ID

IllegalStateException - If any listeners were registered already

reserveEventIdSpace

public void reserveEventIdSpace(int highestId)

Pre-allocates internal data structures for storing event IDs up to highestId.

Parameters:

highestId - The highest event ID

Since:

2.11.0

on

public final EventEmitter on(String name,
 GenericRunnable runnable)

Alias for addEventListener(String, GenericRunnable).

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

on

public final EventEmitter on(String name,
 GenericRunnable.A0 runnable)

Alias for addEventListener(String, GenericRunnable) for zero-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

on

public final EventEmitter on(String name,
 GenericRunnable.A1<?> runnable)

Alias for addEventListener(String, GenericRunnable) for single-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

on

public final EventEmitter on(String name,
 GenericRunnable.A2<?,?> runnable)

Alias for addEventListener(String, GenericRunnable) for two-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

on

public final EventEmitter on(String name,
 GenericRunnable.A3<?,?,?> runnable)

Alias for addEventListener(String, GenericRunnable) for three-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

on

public final EventEmitter on(String name,
 GenericRunnable.A4<?,?,?,?> runnable)

Alias for addEventListener(String, GenericRunnable) for four-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

once

public final EventEmitter once(String name,
 GenericRunnable runnable)

Alias for addEventListenerOnce(String, GenericRunnable).

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

once

public final EventEmitter once(String name,
 GenericRunnable.A0 runnable)

Alias for addEventListenerOnce(String, GenericRunnable) for zero-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

once

public final EventEmitter once(String name,
 GenericRunnable.A1<?> runnable)

Alias for addEventListenerOnce(String, GenericRunnable) for single-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

once

public final EventEmitter once(String name,
 GenericRunnable.A2<?,?> runnable)

Alias for addEventListenerOnce(String, GenericRunnable) for two-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

once

public final EventEmitter once(String name,
 GenericRunnable.A3<?,?,?> runnable)

Alias for addEventListenerOnce(String, GenericRunnable) for three-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

once

public final EventEmitter once(String name,
 GenericRunnable.A4<?,?,?,?> runnable)

Alias for addEventListenerOnce(String, GenericRunnable) for four-argument events.

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

Since:

2.11.0

off

public final EventEmitter off(String name,
 GenericRunnable runnable)

Alias for removeEventListener(String, GenericRunnable).

Parameters:

name - The event name

runnable - The event listener

Returns:

This EventEmitter

emit

public final int emit(String name,
 Object... args)

Alias for runEvent(String, Object...).

Parameters:

name - The event name

args - The arguments to pass to the event listeners

Returns:

The number of registered listeners

emit

public final int emit(int id,
 Object... args)

Alias for runEvent(int, Object...).

Parameters:

id - The event ID

args - The arguments to pass to the event listeners

Returns:

The number of registered listeners

prependEventListener

public void prependEventListener(String name,
 GenericRunnable runnable)

Registers the given event listener for the given event name. The last event listener registered with this method will always be run first among the set of registered event listeners.

Parameters:

name - The event name

runnable - The event listener

See Also:

• addEventListener(String, GenericRunnable)

addEventListener

public void addEventListener(String name,
 GenericRunnable runnable)

Registers the given event listener for the given event name.

Parameters:

name - The event name

runnable - The event listener

Throws:

IllegalStateException - If fastAccess is enabled and the given event name was not created using createEventId(String, int)

See Also:

• on(String, GenericRunnable)
• prependEventListener(String, GenericRunnable)
• addEventListenerOnce(String, GenericRunnable)
• removeEventListener(String, GenericRunnable)
• setDefaultEventListener(String, GenericRunnable)

addEventListenerOnce

public void addEventListenerOnce(String name,
 GenericRunnable runnable)

Registers the given event listener for the given event name. If the an event with the given name is executed, this listener will be unregistered before its execution, causing the event listener to only run once.

Parameters:

name - The event name

runnable - The event listener

Throws:

IllegalStateException - If fastAccess is enabled and the given event name was not created using createEventId(String, int)

See Also:

• addEventListener(String, GenericRunnable)

removeEventListener

public void removeEventListener(String name,
 GenericRunnable runnable)

Removes the given event listener from the event with the given name.

The default event listener may also be removed using this method.

Parameters:

name - The event name

runnable - The event listener

See Also:

• addEventListener(String, GenericRunnable)
• removeAllEventListeners(String)
• removeDefaultEventListener(String)

removeAllEventListeners

public void removeAllEventListeners(String name)

Removes all event listeners from the event with the given name, including the default listener.

Parameters:

name - The event name

See Also:

• removeEventListener(String, GenericRunnable)

getEventListenerCount

public int getEventListenerCount(String name)

Returns the number of event listeners registered for the given event name, excluding the default listener.

Parameters:

name - The event name

Returns:

The number of listeners

getEventNames

public Set<String> getEventNames()

Returns an unmodifiable set of known event names. This includes names of events that were ever passed to runEvent(java.lang.String,java.lang.Object...), addEventListener(String, GenericRunnable) or similar methods. This does not always exclude event names for which no listeners are registered.

Returns:

The set of known event names

getEventListeners

public List<GenericRunnable> getEventListeners(String name)

Returns an unmodifiable, possibly empty, list of the event listeners registered for the given event name, excluding the default listener.

Parameters:

name - The event name

Returns:

The list of event listeners

isEventRegistered

public boolean isEventRegistered(String name)

Returns true if the given event name is a known event. An event is known if there are any listeners registered for it or if it was registered using createEventId(String, int).

Parameters:

name - The event name

Returns:

true if the given event name is a known event

See Also:

• getEventNames()

setDefaultEventListener

public void setDefaultEventListener(String name,
 GenericRunnable runnable)

Registers the default event listener for the given event name. This event listener is called if and only if there are no other (regular) event listeners registered for the event.

Only a single default event listener can be registered per event. Any previous set default event listeners are overriden.

Parameters:

name - The event name

runnable - The default event listener

Throws:

IllegalStateException - If fastAccess is enabled and the given event name was not created using createEventId(String, int)

Since:

2.11.0

See Also:

• removeDefaultEventListener(String)
• addEventListener(String, GenericRunnable)

removeDefaultEventListener

public void removeDefaultEventListener(String name)

Removes the default event listener of the given event name.

Parameters:

name - The event name

Since:

2.11.0

See Also:

• setDefaultEventListener(String, GenericRunnable)
• removeEventListener(String, GenericRunnable)

getDefaultEventListener

public GenericRunnable getDefaultEventListener(String name)

Returns the default event listener of the given event name.

Parameters:

name - The event name

Returns:

The registered default event listener, or null if there is none

Since:

2.11.0

setCoalesceListenerErrors

public void setCoalesceListenerErrors(boolean coalesceListenerErrors)

If set to true, all listeners for an event will always be executed regardless of errors thrown at the listener-level. If set to false, event execution will be canceled at the first thrown exception. The default is true.

Parameters:

coalesceListenerErrors - true to always execute all listeners

See Also:

• EventEmitter

runEvent

public int runEvent(String name,
 Object... args)

Dispatches an event with the given name.

The set of listeners executed for this event is determined once before the first listener is executed. As a consequence, removing a subsequent event listener in an event listener for the same event may still cause the removed event listener to be executed one last time.

Parameters:

name - The event name

args - The arguments to pass to the event listeners

Returns:

The number of registered listeners

Throws:

ExecutionFailedException - If at least one listener failed to execute

See Also:

• EventEmitter

runEvent

public int runEvent(int id,
 Object... args)

Dispatches an event with the given fastAccess event ID.

See runEvent(String, Object...) for more information.

Parameters:

id - The event ID

args - The arguments to pass to the event listeners

Returns:

The number of registered listeners

Throws:

IllegalStateException - If fastAccess is not enabled

IllegalArgumentException - If the given id is not a valid ID

ExecutionFailedException - If at least one listener failed to execute

See Also:

• createEventId(String, int)
• EventEmitter