View Javadoc
1   package org.djutils.event;
2   
3   import java.io.Serializable;
4   import java.util.List;
5   import java.util.Set;
6   
7   import org.djutils.event.ref.Reference;
8   import org.djutils.event.ref.ReferenceType;
9   
10  /**
11   * The EventProducer forms the reference implementation of the EventProducerInterface. Objects extending this class are provided
12   * all the functionalities for registration and event firing. The storage of the listeners is done in a Map with the EventType
13   * as the key, and a List of References (weak or strong) to the Listeners. The class uses a helper class EventProducerImpl to do
14   * the real work, and avoid code duplication.
15   * <p>
16   * Copyright (c) 2002-2020 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
17   * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
18   * distributed under a three-clause BSD-style license, which can be found at
19   * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>. This class was
20   * originally part of the DSOL project, see <a href="https://simulation.tudelft.nl/dsol/manual" target="_blank">
21   * https://simulation.tudelft.nl/dsol/manual</a>.
22   * </p>
23   * @author <a href="https://www.linkedin.com/in/peterhmjacobs">Peter Jacobs </a>
24   * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
25   */
26  public abstract class EventProducer implements EventProducerInterface, Serializable
27  {
28      /** The default serial version UID for serializable classes. */
29      private static final long serialVersionUID = 20140830L;
30  
31      /** The EventProducer helper class with the actual implementation to avoid code duplication. */
32      @SuppressWarnings("checkstyle:visibilitymodifier")
33      protected final EventProducerImpl eventProducerImpl;
34  
35      /**
36       * Constructs a new EventProducer and checks for duplicate values in event types.
37       */
38      public EventProducer()
39      {
40          this.eventProducerImpl = new EventProducerImpl(this);
41      }
42  
43      /** {@inheritDoc} */
44      @Override
45      public abstract Serializable getSourceId(); // without RemoteException
46  
47      /** {@inheritDoc} */
48      @Override
49      public final synchronized boolean addListener(final EventListenerInterface listener, final EventType eventType)
50      {
51          return this.eventProducerImpl.addListener(listener, eventType);
52      }
53  
54      /** {@inheritDoc} */
55      @Override
56      public final synchronized boolean addListener(final EventListenerInterface listener, final EventType eventType,
57              final ReferenceType referenceType)
58      {
59          return this.eventProducerImpl.addListener(listener, eventType, referenceType);
60      }
61  
62      /** {@inheritDoc} */
63      @Override
64      public final synchronized boolean addListener(final EventListenerInterface listener, final EventType eventType,
65              final int position)
66      {
67          return this.eventProducerImpl.addListener(listener, eventType, position);
68      }
69  
70      /** {@inheritDoc} */
71      @Override
72      public final synchronized boolean addListener(final EventListenerInterface listener, final EventType eventType,
73              final int position, final ReferenceType referenceType)
74      {
75          return this.eventProducerImpl.addListener(listener, eventType, position, referenceType);
76      }
77  
78      /**
79       * Transmit an event to all interested listeners.
80       * @param event EventInterface; the event
81       * @return EventInterface; the event (for method chaining)
82       */
83      protected synchronized EventInterfacetInterface">EventInterface fireEvent(final EventInterface event)
84      {
85          return this.eventProducerImpl.fireEvent(event);
86      }
87  
88      /**
89       * Transmit an event with a serializable object as payload to all interested listeners.
90       * @param eventType EventType; the eventType of the event
91       * @param value Serializable; the object sent with the event
92       * @return Serializable; the payload
93       */
94      protected Serializable fireEvent(final EventType eventType, final Serializable value)
95      {
96          return this.eventProducerImpl.fireEvent(eventType, value);
97      }
98  
99      /**
100      * Transmit an event with no payload object to all interested listeners.
101      * @param eventType EventType; the eventType of the event
102      */
103     protected void fireEvent(final EventType eventType)
104     {
105         this.eventProducerImpl.fireEvent(eventType);
106     }
107 
108     /**
109      * Transmit a time-stamped event with a Serializable object (payload) to all interested listeners.
110      * @param eventType EventType; the eventType of the event.
111      * @param value Serializable; the payload sent with the event
112      * @param time C; a time stamp for the event
113      * @return Serializable; the payload
114      * @param <C> the comparable type to indicate the time when the event is fired
115      */
116     protected <C extends Comparable<C> & Serializable> Serializable fireTimedEvent(final EventType eventType,
117             final Serializable value, final C time)
118     {
119         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
120     }
121 
122     /**
123      * Transmit an event with a one byte payload to all interested listeners.
124      * @param eventType EventType; the eventType of the event
125      * @param value byte; the payload
126      * @return byte; the payload
127      */
128     protected byte fireEvent(final EventType eventType, final byte value)
129     {
130         return this.eventProducerImpl.fireEvent(eventType, value);
131     }
132 
133     /**
134      * Transmit a time-stamped event with a one byte payload to all interested listeners.
135      * @param eventType EventType; the eventType of the event
136      * @param value byte; the payload
137      * @param time C; a time stamp for the event
138      * @param <C> the comparable type to indicate the time when the event is fired
139      * @return byte; the payload
140      */
141     protected <C extends Comparable<C> & Serializable> byte fireTimedEvent(final EventType eventType, final byte value,
142             final C time)
143     {
144         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
145     }
146 
147     /**
148      * Transmit an event with a boolean payload to all interested listeners.
149      * @param eventType EventType; the eventType of the event
150      * @param value boolean; the payload
151      * @return boolean; the payload
152      */
153     protected boolean fireEvent(final EventType eventType, final boolean value)
154     {
155         return this.eventProducerImpl.fireEvent(eventType, value);
156     }
157 
158     /**
159      * Transmit a time-stamped event with a boolean payload to all interested listeners.
160      * @param eventType EventType; the eventType of the event
161      * @param value boolean; the payload
162      * @param time C; a time stamp for the event
163      * @param <C> the comparable type to indicate the time when the event is fired
164      * @return boolean; the payload
165      */
166     protected <C extends Comparable<C> & Serializable> boolean fireTimedEvent(final EventType eventType, final boolean value,
167             final C time)
168     {
169         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
170     }
171 
172     /**
173      * Transmit an event with a double value payload to all interested listeners.
174      * @param eventType EventType; the eventType of the event
175      * @param value double; the payload
176      * @return double; the payload
177      */
178     protected double fireEvent(final EventType eventType, final double value)
179     {
180         return this.eventProducerImpl.fireEvent(eventType, value);
181     }
182 
183     /**
184      * Transmit a time-stamped event with a double value payload to interested listeners.
185      * @param eventType EventType; the eventType of the event
186      * @param value double; the payload
187      * @param time C; a time stamp for the event
188      * @param <C> the comparable type to indicate the time when the event is fired
189      * @return double; the payload
190      */
191     protected <C extends Comparable<C> & Serializable> double fireTimedEvent(final EventType eventType, final double value,
192             final C time)
193     {
194         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
195     }
196 
197     /**
198      * Transmit an event with an integer payload to all interested listeners.
199      * @param eventType EventType; the eventType of the event
200      * @param value int; the payload
201      * @return int; the payload
202      */
203     protected int fireEvent(final EventType eventType, final int value)
204     {
205         return this.eventProducerImpl.fireEvent(eventType, value);
206     }
207 
208     /**
209      * Transmit a time-stamped event with an integer payload to all interested listeners.
210      * @param eventType EventType; the eventType of the event
211      * @param value int; the payload
212      * @param time C; a time stamp for the event
213      * @param <C> the comparable type to indicate the time when the event is fired
214      * @return int; the payload
215      */
216     protected <C extends Comparable<C> & Serializable> int fireTimedEvent(final EventType eventType, final int value,
217             final C time)
218     {
219         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
220     }
221 
222     /**
223      * Transmit an event with a long payload to all interested listeners.
224      * @param eventType EventType; the eventType of the event
225      * @param value long; the payload
226      * @return long; the payload
227      */
228     protected long fireEvent(final EventType eventType, final long value)
229     {
230         return this.eventProducerImpl.fireEvent(eventType, value);
231     }
232 
233     /**
234      * Transmit a time-stamped event with a long payload to all interested listeners.
235      * @param eventType EventType; the eventType of the event
236      * @param value long; the payload
237      * @param time C; a time stamp for the event
238      * @param <C> the comparable type to indicate the time when the event is fired
239      * @return long; the payload
240      */
241     protected <C extends Comparable<C> & Serializable> long fireTimedEvent(final EventType eventType, final long value,
242             final C time)
243     {
244         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
245     }
246 
247     /**
248      * Transmit an event with a short payload to all interested listeners.
249      * @param eventType EventType; the eventType of the event
250      * @param value short; the payload
251      * @return short; the payload
252      */
253     protected short fireEvent(final EventType eventType, final short value)
254     {
255         return this.eventProducerImpl.fireEvent(eventType, value);
256     }
257 
258     /**
259      * Transmit a time-stamped event with a short payload to all interested listeners.
260      * @param eventType EventType; the eventType of the event
261      * @param value short; the payload
262      * @param time C; a time stamp for the event
263      * @param <C> the comparable type to indicate the time when the event is fired
264      * @return short; the payload
265      */
266     protected <C extends Comparable<C> & Serializable> short fireTimedEvent(final EventType eventType, final short value,
267             final C time)
268     {
269         return this.eventProducerImpl.fireTimedEvent(eventType, value, time);
270     }
271 
272     /**
273      * Remove all the listeners from this event producer.
274      * @return int; the number of removed event types
275      */
276     protected synchronized int removeAllListeners()
277     {
278         return this.eventProducerImpl.removeAllListeners();
279     }
280 
281     /**
282      * Removes all the listeners of a class from this event producer.
283      * @param ofClass Class&lt;?&gt;; the class or superclass
284      * @return int; the number of removed listeners
285      */
286     protected synchronized int removeAllListeners(final Class<?> ofClass)
287     {
288         return this.eventProducerImpl.removeAllListeners(ofClass);
289 
290     }
291 
292     /** {@inheritDoc} */
293     @Override
294     public final synchronized boolean removeListener(final EventListenerInterface listener, final EventType eventType)
295     {
296         return this.eventProducerImpl.removeListener(listener, eventType);
297     }
298 
299     /** {@inheritDoc} */
300     @Override
301     public boolean hasListeners()
302     {
303         return this.eventProducerImpl.hasListeners();
304     }
305 
306     /** {@inheritDoc} */
307     @Override
308     public synchronized int numberOfListeners(final EventType eventType)
309     {
310         return this.eventProducerImpl.numberOfListeners(eventType);
311     }
312 
313     /** {@inheritDoc} */
314     @Override
315     public synchronized Set<EventType> getEventTypesWithListeners()
316     {
317         return this.eventProducerImpl.getEventTypesWithListeners();
318     }
319 
320     /**
321      * Return a safe copy of the list of (strong or weak) references to the registered listeners for the provided event type, or
322      * an empty list when nothing is registered for this event type. The method never returns a null pointer, so it is safe to
323      * use the result directly in an iterator. The references to the listeners are the original references, so not safe copies.
324      * @param eventType EventType; the event type to look up the listeners for
325      * @return List&lt;Reference&lt;EventListenerInterface&gt;&gt;; the list of references to the listeners for this event type,
326      *         or an empty list when the event type is not registered
327      */
328     protected List<Reference<EventListenerInterface>> getListenerReferences(final EventType eventType)
329     {
330         return this.eventProducerImpl.getListenerReferences(eventType);
331     }
332 
333 }