From dca65df9bdd8b995e404a1f0c8de9c867ac76e81 Mon Sep 17 00:00:00 2001 From: kske Date: Wed, 4 Dec 2019 23:27:17 +0100 Subject: [PATCH] Added Javadoc to event related classes and StatusTrayIcon --- src/main/java/envoy/client/LocalDB.java | 1 - src/main/java/envoy/client/event/Event.java | 1 + .../java/envoy/client/event/EventBus.java | 57 ++++++++++++++++--- .../java/envoy/client/ui/StatusTrayIcon.java | 28 ++++++++- 4 files changed, 75 insertions(+), 12 deletions(-) diff --git a/src/main/java/envoy/client/LocalDB.java b/src/main/java/envoy/client/LocalDB.java index bf6f01a..c080541 100644 --- a/src/main/java/envoy/client/LocalDB.java +++ b/src/main/java/envoy/client/LocalDB.java @@ -49,7 +49,6 @@ public class LocalDB { * @param client the user that is logged in with this client * @since Envoy v0.1-alpha */ - public LocalDB(User sender) { this.sender = sender; try { diff --git a/src/main/java/envoy/client/event/Event.java b/src/main/java/envoy/client/event/Event.java index 5d2e8a3..9db2477 100644 --- a/src/main/java/envoy/client/event/Event.java +++ b/src/main/java/envoy/client/event/Event.java @@ -6,6 +6,7 @@ package envoy.client.event; * Created: 04.12.2019
* * @author Kai S. K. Engelbart + * @since Envoy v0.2-alpha */ public interface Event { diff --git a/src/main/java/envoy/client/event/EventBus.java b/src/main/java/envoy/client/event/EventBus.java index f1c40fc..f6da3f5 100644 --- a/src/main/java/envoy/client/event/EventBus.java +++ b/src/main/java/envoy/client/event/EventBus.java @@ -5,28 +5,67 @@ import java.util.Arrays; import java.util.List; /** - * Project: envoy-clientChess
- * File: EventBus.javaEvent.java
+ * This class handles events by allowing {@link EventHandler} object to register + * themselves and then be notified about certain events dispatched by the event + * bus.
+ *
+ * The event bus is a singleton and can be used across the entire application to + * guarantee the propagation of events. + * Project: envoy-client
+ * File: EventBus.java
* Created: 04.12.2019
- * + * * @author Kai S. K. Engelbart + * @since Envoy v0.2-alpha */ public class EventBus { - private static EventBus eventBus; - + /** + * Contains all {@link EventHandler} instances registered at this + * {@link EventBus}. + */ private List handlers = new ArrayList<>(); + /** + * The singleton instance of this {@link EventBus} that is used across the + * entire application. + */ + private static EventBus eventBus = new EventBus(); + + /** + * This constructor is not accessible from outside this class because a + * singleton instance of it is provided by the {@link EventBus#getInstance()} + * method. + */ private EventBus() {} - public static EventBus getInstance() { - if (eventBus == null) eventBus = new EventBus(); - return eventBus; - } + /** + * @return the singleton instance of the {@link EventBus} + * @since Envoy v0.2-alpha + */ + public static EventBus getInstance() { return eventBus; } + /** + * Registers a list of {@link EventHandler} objects to be notified when a + * {@link Event} is dispatched that they are subscribed to. + * + * @param handlers the {@link EventHandler} objects to register + * @since Envoy v0.2-alpha + */ public void register(EventHandler... handlers) { this.handlers.addAll(Arrays.asList(handlers)); } + /** + * Dispatches a {@link Event} to every {@link EventHandler} subscribed to it. + * + * @param event the {@link Event} to dispatch + * @since Envoy v0.2-alpha + */ public void dispatch(Event event) { handlers.stream().filter(h -> h.supports().contains(event.getClass())).forEach(h -> h.handle(event)); } + /** + * @return a list of all {@link EventHandler} instances currently registered at + * this {@link EventBus} + * @since Envoy v0.2-alpha + */ public List getHandlers() { return handlers; } } diff --git a/src/main/java/envoy/client/ui/StatusTrayIcon.java b/src/main/java/envoy/client/ui/StatusTrayIcon.java index ab668e1..951fbd4 100644 --- a/src/main/java/envoy/client/ui/StatusTrayIcon.java +++ b/src/main/java/envoy/client/ui/StatusTrayIcon.java @@ -27,8 +27,20 @@ import envoy.exception.EnvoyException; */ public class StatusTrayIcon implements EventHandler { + /** + * The {@link TrayIcon} provided by the System Tray API for controlling the + * system tray. This includes displaying the icon, but also creating + * notifications when new messages are received. + */ private TrayIcon trayIcon; + /** + * Creates a {@link StatusTrayIcon} with the Envoy logo, a tool tip and a pop-up + * menu. + * + * @throws EnvoyException if the currently used OS does not support the System + * Tray API + */ public StatusTrayIcon() throws EnvoyException { if (!SystemTray.isSupported()) throw new EnvoyException("The Envoy tray icon is not supported."); @@ -50,7 +62,9 @@ public class StatusTrayIcon implements EventHandler { /** * Makes this {@link StatusTrayIcon} appear in the system tray. * - * @throws EnvoyException + * @throws EnvoyException if the status icon could not be attaches to the system + * tray for system-internal reasons + * @since Envoy v0.2-alpha */ public void show() throws EnvoyException { try { @@ -61,13 +75,23 @@ public class StatusTrayIcon implements EventHandler { } /** - * Notifies the user of a message by displaying a pop-up. + * Notifies the user of a message by displaying a pop-up every time a new + * message is received. + * + * @since Envoy v0.2-alpha */ @Override public void handle(Event event) { trayIcon.displayMessage("New message received", ((MessageCreationEvent) event).get().getContent().get(0).getText(), MessageType.INFO); } + /** + * The {@link StatusTrayIcon} only reacts to {@link MessageCreationEvent} + * instances which signify newly received messages. + * + * @return A set with the single element {@code MessageCreationEvent.class} + * @since Envoy v0.2-alpha + */ @Override public Set>> supports() { Set>> supportedEvents = new HashSet<>();