Package org.djutils.event

Class LocalEventProducer

java.lang.Object

org.djutils.event.LocalEventProducer

All Implemented Interfaces:

Serializable, Remote, EventProducer

Direct Known Subclasses:

EventProducingCollection, EventProducingIterator, EventProducingList, EventProducingMap, EventProducingSet

public class LocalEventProducer
extends Object
implements EventProducer, Serializable

The LocalEventProducer defines the registration and fireEvent operations of an event producer. This behavior includes adding and removing listeners for a specific event type, and firing events for all kinds of different payloads. The EventListener and EventProducer together form a combination of the Publish-Subscribe design pattern and the Observer design pattern using the notify(event) method. See https://en.wikipedia.org/wiki/Publish-subscribe_pattern, https://en.wikipedia.org/wiki/Observer_pattern, and https://howtodoinjava.com/design-patterns/behavioral/observer-design-pattern/.

The EventProducer forms the reference implementation of the publish side of the pub/sub design pattern. The storage of the listeners is done in a Map with the EventType as the key, and a List of References (weak or strong) to the Listeners. Note that the term 'Local' used in the class name is opposed to remote event producers such as the RmiEventProducer.

Copyright (c) 2002-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. This class was originally part of the DSOL project, see https://simulation.tudelft.nl/dsol/manual.

Author:

Peter Jacobs , Alexander Verbraeck

See Also:

Serialized Form

Field Summary

Fields inherited from interface org.djutils.event.EventProducer

FIRST_POSITION, LAST_POSITION

Constructor Summary

Constructors

Constructor	Description
LocalEventProducer()

Method Summary

Modifier and Type	Method	Description
boolean	addListener(EventListener listener, EventType eventType)	Add a listener as strong reference to the BEGINNING of a queue of listeners.
boolean	addListener(EventListener listener, EventType eventType, int position)	Add a listener as strong reference to the specified position of a queue of listeners.
boolean	addListener(EventListener listener, EventType eventType, int position, ReferenceType referenceType)	Add a listener to the specified position of a queue of listeners.
boolean	addListener(EventListener listener, EventType eventType, ReferenceType referenceType)	Add a listener to the BEGINNING of a queue of listeners.
void	fireEvent(Event event)	Transmit an event to all subscribed listeners.
void	fireEvent(EventType eventType)	Transmit an event with no payload object to all interested listeners.
void	fireEvent(EventType eventType, Serializable value)	Transmit an event with a serializable object as payload to all interested listeners.
<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.
<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.
<C extends Comparable<C> & Serializable> void	fireTimedEvent(TimedEvent<C> event)	Transmit a time-stamped event to all interested listeners.
void	fireUnverifiedEvent(EventType eventType)	Transmit an event with no payload object to all interested listeners.
void	fireUnverifiedEvent(EventType eventType, Serializable value)	Transmit an event with a serializable object as payload to all interested listeners.
<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.
<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.
Set<EventType>	getEventTypesWithListeners()	Return the EventTypes for which the EventProducer has listeners.
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.
boolean	hasListeners()	Return whether the EventProducer has listeners.
int	numberOfListeners(EventType eventType)	Return the number of listeners for the provided EventType.
int	removeAllListeners()	Remove all the listeners from this event producer.
int	removeAllListeners(Class<?> ofClass)	Removes all the listeners of a class from this event producer.
boolean	removeListener(EventListener listener, EventType eventType)	Remove the subscription of a listener for a specific event.

Methods inherited from class java.lang.Object

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

Constructor Detail

LocalEventProducer

public LocalEventProducer()

Method Detail

getEventListenerMap

public EventListenerMap getEventListenerMap()

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

Specified by:

getEventListenerMap in interface EventProducer

Returns:

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

addListener

public boolean addListener(EventListener listener,
                           EventType eventType,
                           int position,
                           ReferenceType referenceType)

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

Specified by:

addListener in interface EventProducer

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

See Also:

WeakReference

addListener

public boolean addListener(EventListener listener,
                           EventType eventType)

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

Specified by:

addListener in interface EventProducer

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

addListener

public boolean addListener(EventListener listener,
                           EventType eventType,
                           ReferenceType referenceType)

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

Specified by:

addListener in interface EventProducer

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

See Also:

WeakReference

addListener

public boolean addListener(EventListener listener,
                           EventType eventType,
                           int position)

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

Specified by:

addListener in interface EventProducer

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

removeAllListeners

public int removeAllListeners()

Remove all the listeners from this event producer.

Specified by:

removeAllListeners in interface EventProducer

Returns:

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

removeAllListeners

public int removeAllListeners(Class<?> ofClass)

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

Specified by:

removeAllListeners in interface EventProducer

Parameters:

ofClass - Class<?>; the class or superclass

Returns:

int; the number of removed listeners

removeListener

public boolean removeListener(EventListener listener,
                              EventType eventType)

Remove the subscription of a listener for a specific event.

Specified by:

removeListener in interface EventProducer

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

hasListeners

public boolean hasListeners()

Return whether the EventProducer has listeners.

Specified by:

hasListeners in interface EventProducer

Returns:

boolean; whether the EventProducer has listeners or not

numberOfListeners

public int numberOfListeners(EventType eventType)

Return the number of listeners for the provided EventType.

Specified by:

numberOfListeners in interface EventProducer

Parameters:

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

Returns:

boolean; whether the EventProducer has listeners or not

getListenerReferences

public 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. 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.

Specified by:

getListenerReferences in interface EventProducer

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

getEventTypesWithListeners

public Set<EventType> getEventTypesWithListeners()

Return the EventTypes for which the EventProducer has listeners.

Specified by:

getEventTypesWithListeners in interface EventProducer

Returns:

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

fireEvent

public void fireEvent(Event event)

Transmit an event to all subscribed listeners.

Specified by:

fireEvent in interface EventProducer

Parameters:

event - Event; the event

fireTimedEvent

public <C extends Comparable<C> & Serializable> void fireTimedEvent(TimedEvent<C> event)

Transmit a time-stamped event to all interested listeners.

Specified by:

fireTimedEvent in interface EventProducer

Type Parameters:

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

Parameters:

event - TimedEvent<C>; the event

fireEvent

public void fireEvent(EventType eventType)

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

Specified by:

fireEvent in interface EventProducer

Parameters:

eventType - EventType; the eventType of the event

fireTimedEvent

public <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.

Specified by:

fireTimedEvent in interface EventProducer

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

fireEvent

public void fireEvent(EventType eventType,
                      Serializable value)

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

Specified by:

fireEvent in interface EventProducer

Parameters:

eventType - EventType; the eventType of the event

value - Serializable; the object sent with the event

fireTimedEvent

public <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.

Specified by:

fireTimedEvent in interface EventProducer

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

fireUnverifiedEvent

public void fireUnverifiedEvent(EventType eventType)

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

Specified by:

fireUnverifiedEvent in interface EventProducer

Parameters:

eventType - EventType; the eventType of the event

fireUnverifiedTimedEvent

public <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.

Specified by:

fireUnverifiedTimedEvent in interface EventProducer

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

fireUnverifiedEvent

public void fireUnverifiedEvent(EventType eventType,
                                Serializable value)

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

Specified by:

fireUnverifiedEvent in interface EventProducer

Parameters:

eventType - EventType; the eventType of the event

value - Serializable; the object sent with the event

fireUnverifiedTimedEvent

public <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.

Specified by:

fireUnverifiedTimedEvent in interface EventProducer

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