Package org.djutils.event

Interface EventProducer

All Superinterfaces:

Remote, Serializable

All Known Implementing Classes:

EventProducingCollection, EventProducingIterator, EventProducingList, EventProducingListIterator, EventProducingMap, EventProducingSet, LocalEventProducer, RmiEventProducer

public interface EventProducer
extends Serializable, Remote

EventProducer is the interface that exposes a few of the methods of the implementation of an EventProducer to the outside world: the ability to add and remove listeners.

Copyright (c) 2022-2023 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.

Author:

Alexander Verbraeck

Field Summary

Fields

Modifier and Type	Field	Description
static int	FIRST_POSITION	The FIRST_POSITION in the queue.
static int	LAST_POSITION	The LAST_POSITION in the queue.

Method Summary

Modifier and Type	Method	Description
default boolean	addListener(EventListener listener, EventType eventType)	Add a listener as strong reference to the BEGINNING of a queue of listeners.
default boolean	addListener(EventListener listener, EventType eventType, int position)	Add a listener as strong reference to the specified position of a queue of listeners.
default boolean	addListener(EventListener listener, EventType eventType, int position, ReferenceType referenceType)	Add a listener to the specified position of a queue of listeners.
default boolean	addListener(EventListener listener, EventType eventType, ReferenceType referenceType)	Add a listener to the BEGINNING of a queue of listeners.
default void	fireEvent(Event event)	Transmit an event to all subscribed listeners.
default void	fireEvent(EventType eventType)	Transmit an event with no payload object to all interested listeners.
default void	fireEvent(EventType eventType, Serializable value)	Transmit an event with a serializable object as payload to all interested listeners.
default <C extends Comparable<C> & Serializable> void	fireTimedEvent(EventType eventType, C time)	Transmit a time-stamped event with a no payload object to all interested listeners.
default <C extends Comparable<C> & Serializable> void	fireTimedEvent(EventType eventType, Serializable value, C time)	Transmit a time-stamped event with a Serializable object (payload) to all interested listeners.
default <C extends Comparable<C> & Serializable> void	fireTimedEvent(TimedEvent<C> event)	Transmit a time-stamped event to all interested listeners.
default void	fireUnverifiedEvent(EventType eventType)	Transmit an event with no payload object to all interested listeners.
default void	fireUnverifiedEvent(EventType eventType, Serializable value)	Transmit an event with a serializable object as payload to all interested listeners.
default <C extends Comparable<C> & Serializable> void	fireUnverifiedTimedEvent(EventType eventType, C time)	Transmit a time-stamped event with a no payload object to all interested listeners.
default <C extends Comparable<C> & Serializable> void	fireUnverifiedTimedEvent(EventType eventType, Serializable value, C time)	Transmit a time-stamped event with a Serializable object (payload) to all interested listeners.
EventListenerMap	getEventListenerMap()	Return the map with the EventListener entries and the reference types.
default Set<EventType>	getEventTypesWithListeners()	Return the EventTypes for which the EventProducer has listeners.
default List<Reference<EventListener>>	getListenerReferences(EventType eventType)	Return a safe copy of the list of (strong or weak) references to the registered listeners for the provided event type, or an empty list when nothing is registered for this event type.
default boolean	hasListeners()	Return whether the EventProducer has listeners.
default int	numberOfListeners(EventType eventType)	Return the number of listeners for the provided EventType.
default int	removeAllListeners()	Remove all the listeners from this event producer.
default int	removeAllListeners(Class<?> ofClass)	Removes all the listeners of a class from this event producer.
default boolean	removeListener(EventListener listener, EventType eventType)	Remove the subscription of a listener for a specific event.

Field Detail

FIRST_POSITION

static final int FIRST_POSITION

The FIRST_POSITION in the queue.

See Also:

Constant Field Values

LAST_POSITION

static final int LAST_POSITION

The LAST_POSITION in the queue.

See Also:

Constant Field Values

Method Detail

addListener

default boolean addListener(EventListener listener,
                            EventType eventType,
                            int position,
                            ReferenceType referenceType)
                     throws RemoteException

Add a listener to the specified position of a queue of listeners.

Parameters:

listener - EventListenerInterface; which is interested at certain events

eventType - EventType; the events of interest

position - int; the position of the listener in the queue

referenceType - ReferenceType; whether the listener is added as a strong or as a weak reference

Returns:

the success of adding the listener. If a listener was already added or an illegal position is provided false is returned

Throws:

RemoteException - on network error

See Also:

WeakReference

addListener

default boolean addListener(EventListener listener,
                            EventType eventType)
                     throws RemoteException

Add a listener as strong reference to the BEGINNING of a queue of listeners.

Parameters:

listener - EventListenerInterface; the listener which is interested at events of eventType

eventType - EventType; the events of interest

Returns:

the success of adding the listener. If a listener was already added false is returned

Throws:

RemoteException - on network error

addListener

default boolean addListener(EventListener listener,
                            EventType eventType,
                            ReferenceType referenceType)
                     throws RemoteException

Add a listener to the BEGINNING of a queue of listeners.

Parameters:

listener - EventListenerInterface; the listener which is interested at events of eventType

eventType - EventType; the events of interest

referenceType - ReferenceType; whether the listener is added as a strong or as a weak reference

Returns:

the success of adding the listener. If a listener was already added false is returned

Throws:

RemoteException - on network error

See Also:

WeakReference

addListener

default boolean addListener(EventListener listener,
                            EventType eventType,
                            int position)
                     throws RemoteException

Add a listener as strong reference to the specified position of a queue of listeners.

Parameters:

listener - EventListenerInterface; the listener which is interested at events of eventType

eventType - EventType; the events of interest

position - int; the position of the listener in the queue

Returns:

the success of adding the listener. If a listener was already added, or an illegal position is provided false is returned

Throws:

RemoteException - on network error

getEventListenerMap

EventListenerMap getEventListenerMap()
                              throws RemoteException

Return the map with the EventListener entries and the reference types.

Returns:

EventListenerMap; the map with the EventListener entries and the reference types

Throws:

RemoteException - on netowrk error

removeAllListeners

default int removeAllListeners()
                        throws RemoteException

Remove all the listeners from this event producer.

Returns:

int; the number of removed event types for which listeners existed

Throws:

RemoteException - on network error

removeAllListeners

default int removeAllListeners(Class<?> ofClass)
                        throws RemoteException

Removes all the listeners of a class from this event producer.

Parameters:

ofClass - Class<?>; the class or superclass

Returns:

int; the number of removed listeners

Throws:

RemoteException - on network error

removeListener

default boolean removeListener(EventListener listener,
                               EventType eventType)
                        throws RemoteException

Remove the subscription of a listener for a specific event.

Parameters:

listener - EventListenerInterface; which is no longer interested

eventType - EventType; the event which is of no interest any more

Returns:

the success of removing the listener. If a listener was not subscribed false is returned

Throws:

RemoteException - on network error

hasListeners

default boolean hasListeners()
                      throws RemoteException

Return whether the EventProducer has listeners.

Returns:

boolean; whether the EventProducer has listeners or not

Throws:

RemoteException - on network error

numberOfListeners

default int numberOfListeners(EventType eventType)
                       throws RemoteException

Return the number of listeners for the provided EventType.

Parameters:

eventType - EventType; the event type to return the number of listeners for

Returns:

boolean; whether the EventProducer has listeners or not

Throws:

RemoteException - on network error

getListenerReferences

default List<Reference<EventListener>> getListenerReferences(EventType eventType)
                                                      throws RemoteException

Return a safe copy of the list of (strong or weak) references to the registered listeners for the provided event type, or an empty list when nothing is registered for this event type. The method never returns a null pointer, so it is safe to use the result directly in an iterator. The references to the listeners are the original references, so not safe copies.

Parameters:

eventType - EventType; the event type to look up the listeners for

Returns:

List<Reference<EventListenerInterface>>; the list of references to the listeners for this event type, or an empty list when the event type is not registered

Throws:

RemoteException - on network error

getEventTypesWithListeners

default Set<EventType> getEventTypesWithListeners()
                                           throws RemoteException

Return the EventTypes for which the EventProducer has listeners.

Returns:

Set<EventType>; the EventTypes for which the EventProducer has registered listeners

Throws:

RemoteException - on netowrk error

fireEvent

default void fireEvent(Event event)
                throws RemoteException

Transmit an event to all subscribed listeners.

Parameters:

event - Event; the event

Throws:

RemoteException - on network error

fireTimedEvent

default <C extends Comparable<C> & Serializable> void fireTimedEvent(TimedEvent<C> event)
                                                              throws RemoteException

Transmit a time-stamped event to all interested listeners.

Type Parameters:

C - the comparable type to indicate the time when the event is fired

Parameters:

event - TimedEvent<C>; the event

Throws:

RemoteException - on network failure

fireEvent

default void fireEvent(EventType eventType)
                throws RemoteException

Transmit an event with no payload object to all interested listeners.

Parameters:

eventType - EventType; the eventType of the event

Throws:

RemoteException - on network failure

fireTimedEvent

default <C extends Comparable<C> & Serializable> void fireTimedEvent(EventType eventType,
                                                                     C time)
                                                              throws RemoteException

Transmit a time-stamped event with a no payload object to all interested listeners.

Type Parameters:

C - the comparable type to indicate the time when the event is fired

Parameters:

eventType - EventType; the eventType of the event.

time - C; a time stamp for the event

Throws:

RemoteException - on network failure

fireEvent

default void fireEvent(EventType eventType,
                       Serializable value)
                throws RemoteException

Transmit an event with a serializable object as payload to all interested listeners.

Parameters:

eventType - EventType; the eventType of the event

value - Serializable; the object sent with the event

Throws:

RemoteException - on network failure

fireTimedEvent

default <C extends Comparable<C> & Serializable> void fireTimedEvent(EventType eventType,
                                                                     Serializable value,
                                                                     C time)
                                                              throws RemoteException

Transmit a time-stamped event with a Serializable object (payload) to all interested listeners.

Type Parameters:

C - the comparable type to indicate the time when the event is fired

Parameters:

eventType - EventType; the eventType of the event.

value - Serializable; the payload sent with the event

time - C; a time stamp for the event

Throws:

RemoteException - on network failure

fireUnverifiedEvent

default void fireUnverifiedEvent(EventType eventType)
                          throws RemoteException

Transmit an event with no payload object to all interested listeners.

Parameters:

eventType - EventType; the eventType of the event

Throws:

RemoteException - on network failure

fireUnverifiedTimedEvent

default <C extends Comparable<C> & Serializable> void fireUnverifiedTimedEvent(EventType eventType,
                                                                               C time)
                                                                        throws RemoteException

Transmit a time-stamped event with a no payload object to all interested listeners.

Type Parameters:

C - the comparable type to indicate the time when the event is fired

Parameters:

eventType - EventType; the eventType of the event.

time - C; a time stamp for the event

Throws:

RemoteException - on network failure

fireUnverifiedEvent

default void fireUnverifiedEvent(EventType eventType,
                                 Serializable value)
                          throws RemoteException

Transmit an event with a serializable object as payload to all interested listeners.

Parameters:

eventType - EventType; the eventType of the event

value - Serializable; the object sent with the event

Throws:

RemoteException - on network failure

fireUnverifiedTimedEvent

default <C extends Comparable<C> & Serializable> void fireUnverifiedTimedEvent(EventType eventType,
                                                                               Serializable value,
                                                                               C time)
                                                                        throws RemoteException

Transmit a time-stamped event with a Serializable object (payload) to all interested listeners.

Type Parameters:

C - the comparable type to indicate the time when the event is fired

Parameters:

eventType - EventType; the eventType of the event.

value - Serializable; the payload sent with the event

time - C; a time stamp for the event

Throws:

RemoteException - on network failure