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-2024 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:

  • Constructor Details

    • LocalEventProducer

      public LocalEventProducer()

  • Method Details

    • getEventListenerMap

      public EventListenerMap getEventListenerMap()
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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:

    • addListener

      public boolean addListener(EventListener listener, EventType eventType)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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:

    • addListener

      public boolean addListener(EventListener listener, EventType eventType, int position)
      Description copied from interface: EventProducer
      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()
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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()
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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()
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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)
      Description copied from interface: EventProducer
      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