1 package org.djutils.event;
2
3 import java.io.Serializable;
4 import java.rmi.RemoteException;
5 import java.util.Set;
6
7 import org.djutils.event.ref.ReferenceType;
8
9 /**
10 * The EventProducerInterface defines the registration operations of an event producer. This behavior includes adding and
11 * removing listeners for a specific event type. The EventListener and EventProducer together form a combination of the
12 * Publish-Subscribe design pattern and the Observer design pattern using the notify(event) method. See
13 * <a href="https://en.wikipedia.org/wiki/Publish-subscribe_pattern" target=
14 * "_blank">https://en.wikipedia.org/wiki/Publish-subscribe_pattern</a>,
15 * <a href="https://en.wikipedia.org/wiki/Observer_pattern" target="_blank">https://en.wikipedia.org/wiki/Observer_pattern</a>,
16 * and <a href="https://howtodoinjava.com/design-patterns/behavioral/observer-design-pattern/" target=
17 * "_blank">https://howtodoinjava.com/design-patterns/behavioral/observer-design-pattern/</a>.
18 * <p>
19 * Copyright (c) 2002-2022 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
20 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
21 * distributed under a three-clause BSD-style license, which can be found at
22 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>. This class was
23 * originally part of the DSOL project, see <a href="https://simulation.tudelft.nl/dsol/manual" target="_blank">
24 * https://simulation.tudelft.nl/dsol/manual</a>.
25 * </p>
26 * @author <a href="https://www.linkedin.com/in/peterhmjacobs">Peter Jacobs </a>
27 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
28 */
29 public interface EventProducerInterface
30 {
31 /** The FIRST_POSITION in the queue. */
32 int FIRST_POSITION = 0;
33
34 /** The LAST_POSITION in the queue. */
35 int LAST_POSITION = -1;
36
37 /**
38 * Provide the sourceId that will be transmitted with the fired Event.
39 * @return Serializable; the sourceId that will be transmitted with the fired Event
40 * @throws RemoteException if a network failure occurs
41 */
42 Serializable getSourceId() throws RemoteException;
43
44 /**
45 * Add a listener as strong reference to the BEGINNING of a queue of listeners.
46 * @param listener EventListenerInterface; the listener which is interested at events of eventType
47 * @param eventType EventTypeInterface; the events of interest
48 * @return the success of adding the listener. If a listener was already added false is returned
49 * @throws RemoteException If a network connection failure occurs.
50 */
51 boolean addListener(EventListenerInterface listener, EventTypeInterface eventType) throws RemoteException;
52
53 /**
54 * Add a listener to the BEGINNING of a queue of listeners.
55 * @param listener EventListenerInterface; the listener which is interested at events of eventType
56 * @param eventType EventTypeInterface; the events of interest
57 * @param referenceType ReferenceType; whether the listener is added as a strong or as a weak reference
58 * @return the success of adding the listener. If a listener was already added false is returned
59 * @throws RemoteException If a network connection failure occurs.
60 * @see org.djutils.event.ref.WeakReference
61 */
62 boolean addListener(EventListenerInterface listener, EventTypeInterface eventType, ReferenceType referenceType)
63 throws RemoteException;
64
65 /**
66 * Add a listener as strong reference to the specified position of a queue of listeners.
67 * @param listener EventListenerInterface; the listener which is interested at events of eventType
68 * @param eventType EventTypeInterface; the events of interest
69 * @param position int; the position of the listener in the queue
70 * @return the success of adding the listener. If a listener was already added, or an illegal position is provided false is
71 * returned
72 * @throws RemoteException If a network connection failure occurs.
73 */
74 boolean addListener(EventListenerInterface listener, EventTypeInterface eventType, int position) throws RemoteException;
75
76 /**
77 * Add a listener to the specified position of a queue of listeners.
78 * @param listener EventListenerInterface; which is interested at certain events
79 * @param eventType EventTypeInterface; the events of interest
80 * @param position int; the position of the listener in the queue
81 * @param referenceType ReferenceType; whether the listener is added as a strong or as a weak reference
82 * @return the success of adding the listener. If a listener was already added or an illegal position is provided false is
83 * returned
84 * @throws RemoteException If a network connection failure occurs.
85 * @see org.djutils.event.ref.WeakReference
86 */
87 boolean addListener(EventListenerInterface listener, EventTypeInterface eventType, int position,
88 ReferenceType referenceType) throws RemoteException;
89
90 /**
91 * Remove the subscription of a listener for a specific event.
92 * @param listener EventListenerInterface; which is no longer interested
93 * @param eventType EventTypeInterface; the event which is of no interest any more
94 * @return the success of removing the listener. If a listener was not subscribed false is returned
95 * @throws RemoteException If a network connection failure occurs.
96 */
97 boolean removeListener(EventListenerInterface listener, EventTypeInterface eventType) throws RemoteException;
98
99 /**
100 * Return whether the EventProducer has listeners.
101 * @return boolean; whether the EventProducer has listeners or not
102 * @throws RemoteException If a network connection failure occurs.
103 */
104 boolean hasListeners() throws RemoteException;
105
106 /**
107 * Return the number of listeners for the provided EventTypeInterface.
108 * @param eventType EventTypeInterface; the event type to return the number of listeners for
109 * @return boolean; whether the EventProducer has listeners or not
110 * @throws RemoteException If a network connection failure occurs.
111 */
112 int numberOfListeners(EventTypeInterface eventType) throws RemoteException;
113
114 /**
115 * Return the EventTypeInterfaces for which the EventProducer has listeners.
116 * @return Set<EventTypeInterface>; the EventTypeInterfaces for which the EventProducer has registered listeners
117 * @throws RemoteException If a network connection failure occurs.
118 */
119 Set<EventTypeInterface> getEventTypesWithListeners() throws RemoteException;
120
121 }