diff --git a/src/main/java/schule/ngb/zm/util/events/EventDispatcher.java b/src/main/java/schule/ngb/zm/util/events/EventDispatcher.java index d001387..4cceefc 100644 --- a/src/main/java/schule/ngb/zm/util/events/EventDispatcher.java +++ b/src/main/java/schule/ngb/zm/util/events/EventDispatcher.java @@ -7,6 +7,60 @@ import java.util.concurrent.ConcurrentMap; import java.util.concurrent.CopyOnWriteArraySet; import java.util.function.BiConsumer; +/** + * Implementierung einer EventListener-API basierend auf dem Artikel + * Skilled + * Listening in Java von Dr. Warren D. MacEvoy. + *

+ * Der {@code EventDispatcher} verwaltet eine Liste von angemeldeten Listenern + * in einem {@link CopyOnWriteArraySet}, dass besonders für Situationen geeignet + * ist, in denen in der Regel wenige Objekte verwaltet werden müssen, auf die + * schnell zugegriffen werden soll und die sich selten ändern. Das trifft in den + * meisten Fällen auf die Listener eines Objekts zu. + *

+ * Um einen {@code EventDispatcher} zu nutzen, muss eine Schnittstelle als + * Unterinterface von {@link Listener} erstellt werden, die Methoden für die + * einzelnen Events definiert. In der Regel wird eine Methode pro Event + * angelegt, aber dies ist nicht unbedingt notwendig. + *

+ * Ein Objekt, dass Events für diese Art von Listener erzeugt, erstellt einen + * {@code EventDispatcher} und + * {@link #registerEventType(String, BiConsumer) registriert} die notwendigen + * Events. + * + *


+ * EventDispatcher<MyEvent, MyEventListener> dispatcher = new EventDispatcher<>();
+ * dispatcher.registerEventType("start", (evt, listener) -> listener.started(evt));
+ * dispatcher.registerEventType("stop", (evt, listener) -> listener.stopped(evt));
+ * 
+ *

+ * Hier werden zwei Events registriert "start" und "stop". Die Bezeichnung der + * Events wird nut intern verwendet. Jedes Event registriert eine Funktion, die + * den Aufruf der Listener-Schnittstelle umsetzt. In der Regel ist dies ein + * Lambda-Ausdruck von zwei Parametern: dem Event-Objekt vom Typ {@code E} und + * der Listener, der aufgerufen werden soll, vom Typ {@code L}. + *

+ * Nun können {@code MyEventListener} angemeldet und Events ausgelöst werden. + * + *


+ * public void addEventListener( MyEventListener listener ) {
+ *     dispatcher.addListener(listener);
+ * }
+ *
+ * public void removeEventListener( MyEventListener listener ) {
+ *     dispatcher.removeListener(listener);
+ * }
+ *
+ * public void methodThatCreatesEvents() {
+ *     dispatcher.dispatchEvent("start", new MyEvent());
+ *     // Do something
+ *     dispatcher.dispatchEvent("stop", new MyEvent());
+ * }
+ * 
+ * + * @param Typ der Event-Objekte. + * @param Typ der verwendeten Listener-Schnittstelle. + */ public class EventDispatcher> { private final CopyOnWriteArraySet listeners; @@ -35,6 +89,7 @@ public class EventDispatcher> { listeners.remove(listener); } + @SuppressWarnings("unused") public boolean hasListeners() { return !listeners.isEmpty(); } diff --git a/src/main/java/schule/ngb/zm/util/events/Listener.java b/src/main/java/schule/ngb/zm/util/events/Listener.java index 45cc666..e5a2456 100644 --- a/src/main/java/schule/ngb/zm/util/events/Listener.java +++ b/src/main/java/schule/ngb/zm/util/events/Listener.java @@ -1,5 +1,11 @@ package schule.ngb.zm.util.events; +/** + * Generische Basisschnittstelle für die Implementierung von EventListenern. + * + * @param Typ der Event-Objekte, die von diesem Listener empfangen werden. + * @see EventDispatcher + */ public interface Listener { }