Improve Documentation in Code #24

Merged
kske merged 2 commits from f/improved-documentation into develop 2021-11-01 21:48:51 +01:00
3 changed files with 39 additions and 13 deletions

View File

@ -66,10 +66,27 @@ public final class EventBus {
return singletonInstance; return singletonInstance;
} }
private final Map<Class<?>, TreeSet<EventHandler>> bindings = /**
new ConcurrentHashMap<>(); * Event handler bindings (target class to handlers registered for that class), does not contain
private final Set<Object> registeredListeners = * other (polymorphic) handlers.
ConcurrentHashMap.newKeySet(); *
* @since 0.0.1
*/
private final Map<Class<?>, TreeSet<EventHandler>> bindings = new ConcurrentHashMap<>();
/**
* Stores all registered event listeners (which declare event handlers) and prevents them from
kske marked this conversation as resolved Outdated
Outdated
Review

Stores all registered listeners. Additionally prevents them from being garbage collected.

Stores all registered listeners. Additionally prevents them from being garbage collected.
* being garbage collected.
*
* @since 0.0.1
*/
private final Set<Object> registeredListeners = ConcurrentHashMap.newKeySet();
/**
kske marked this conversation as resolved
Review

The current event dispatching state for the current thread.

The current event dispatching state for the current thread.
* The current event dispatching state, local to each thread.
*
* @since 0.1.0
*/
private final ThreadLocal<DispatchState> dispatchState = private final ThreadLocal<DispatchState> dispatchState =
ThreadLocal.withInitial(DispatchState::new); ThreadLocal.withInitial(DispatchState::new);
@ -79,6 +96,7 @@ public final class EventBus {
* *
* @param event the event to dispatch * @param event the event to dispatch
* @throws EventBusException if an event handler isn't accessible or has an invalid signature * @throws EventBusException if an event handler isn't accessible or has an invalid signature
* @throws NullPointerException if the specified event is {@code null}
* @since 0.0.1 * @since 0.0.1
*/ */
public void dispatch(Object event) throws EventBusException { public void dispatch(Object event) throws EventBusException {
@ -173,8 +191,9 @@ public final class EventBus {
* Registers an event listener at this event bus. * Registers an event listener at this event bus.
* *
* @param listener the listener to register * @param listener the listener to register
* @throws EventBusException if the listener is already registered or a declared event handler * @throws EventBusException if the listener is already registered or a declared event
* does not comply with the specification * handler does not comply with the specification
* @throws NullPointerException if the specified listener is {@code null}
* @since 0.0.1 * @since 0.0.1
* @see Event * @see Event
*/ */
@ -229,6 +248,7 @@ public final class EventBus {
Objects.requireNonNull(listener); Objects.requireNonNull(listener);
logger.log(Level.INFO, "Removing event listener {0}", listener.getClass().getName()); logger.log(Level.INFO, "Removing event listener {0}", listener.getClass().getName());
// Remove bindings from binding map
for (var binding : bindings.values()) { for (var binding : bindings.values()) {
var it = binding.iterator(); var it = binding.iterator();
while (it.hasNext()) { while (it.hasNext()) {
@ -239,6 +259,8 @@ public final class EventBus {
} }
} }
} }
// Remove the listener itself
registeredListeners.remove(listener); registeredListeners.remove(listener);
} }

View File

@ -1,14 +1,18 @@
package dev.kske.eventbus.core; package dev.kske.eventbus.core;
/** /**
* This runtime exception is thrown when an event bus error occurs. This can * This unchecked exception is specific to the event bus and can be thrown under the following
Review

I think it would be kinda funny to have an EventBusException that can be thrown under (the bus and) the following…

I think it would be kinda funny to have an `EventBusException` that `can be thrown under (the bus and) the following…`
* either occur while registering event listeners with invalid handlers, or when * circumstances:
* an event handler throws an exception. * <ul>
* <li>An event handler throws an exception (which is stored as the cause)</li>
kske marked this conversation as resolved Outdated
Outdated
Review

it

Alternatively:
stored

it Alternatively: stored
* <li>An event listener with an invalid event handler is registered</li>
* <li>{@link EventBus#cancel()} is invoked from outside an active dispatch thread</li>
* </ul>
* *
* @author Kai S. K. Engelbart * @author Kai S. K. Engelbart
* @since 0.0.1 * @since 0.0.1
*/ */
public class EventBusException extends RuntimeException { public final class EventBusException extends RuntimeException {
private static final long serialVersionUID = 1L; private static final long serialVersionUID = 1L;

View File

@ -9,7 +9,7 @@
<packaging>pom</packaging> <packaging>pom</packaging>
<name>Event Bus</name> <name>Event Bus</name>
<description>An event handling framework for Java utilizing annotations.</description> <description>An event handling library for Java utilizing annotations.</description>
<url>https://git.kske.dev/kske/event-bus</url> <url>https://git.kske.dev/kske/event-bus</url>
<modules> <modules>