From ad29a93ccb620b2bb825b510caf80df0abebd0d3 Mon Sep 17 00:00:00 2001 From: kske Date: Wed, 24 Nov 2021 10:37:21 +0100 Subject: [PATCH 1/5] Add debugging section to README --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 84a0d31..4ce68a9 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,17 @@ The same applies when an exception event handler throws an exception. To avoid this, system events never cause system events and instead just issue a warning to the logger. +## Debugging + +In more complex setups, taking a look at the event handler execution order can be helpful for debugging. +Event Bus offers a method for this purpose which can be used as follows: + +```java +System.out.println(EventBus.getInstance().printExecutionOrder(SimpleEvent.class)); +``` + +Then, the execution order can be inspected in the console. + ## Installation Event Bus is available in Maven Central. From d1c4bcc7eb7c8e7c7db47077b108b83c6521be19 Mon Sep 17 00:00:00 2001 From: kske Date: Wed, 24 Nov 2021 10:45:58 +0100 Subject: [PATCH 2/5] Add callback listener section to README --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 4ce68a9..e05d890 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,18 @@ private void onSimpleEvent() { Make sure that you **do not** both declare a parameter and specify the event type in the annotation, as this would be ambiguous. +## Callback listeners + +While defining event handlers as annotated methods is rather simple and readable, sometimes a more flexible approach is required. +For this reason, there are callback event handlers that allow the registration of an "inline" event listener consisting of just one handler in the form of a consumer: + +```java +EventBus.getInstance().registerListener(SimpleEvent.class, e -> System.out.println("Received " + e)); +``` + +The event type has to be defined explicitly, with the priority and polymorphism parameters being optional. +If you intend to remove the listener later, remember to keep a reference to it, as you would have to clear the entire event bus if you didn't. + ## Listener-Level Properties When defining a dedicated event listener that, for example, performs pre- or post-processing, all event handlers will probably have the same non-standard priority. From 3fccb809c8f8c5d17fb20c92ac1a7f608cdbdbb5 Mon Sep 17 00:00:00 2001 From: kske Date: Wed, 24 Nov 2021 10:49:30 +0100 Subject: [PATCH 3/5] Move installation section up in README --- README.md | 54 +++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index e05d890..493d672 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,33 @@ private static void onSimpleEvent(SimpleEvent event) { ... } is technically possible, however you would still have to create an instance of the event listener to register it at an event bus. +## Installation + +Event Bus is available in Maven Central. +To include it inside your project, just add the following dependency to your `pom.xml`: + +```xml + + + dev.kske + event-bus-core + 1.1.0 + + +``` + +Then, require the Event Bus Core module in your `module-info.java`: + +```java +requires dev.kske.eventbus.core; +``` + +If you intend to use event handlers that are inaccessible to Event Bus by means of Java language access control, make sure to allow reflective access from your module: + +```java +opens my.module to dev.kske.eventbus.core; +``` + ## Polymorphic Event Handlers On certain occasions it's practical for an event handler to accept both events of the specified type, as well as subclasses of that event. @@ -182,33 +209,6 @@ System.out.println(EventBus.getInstance().printExecutionOrder(SimpleEvent.class) Then, the execution order can be inspected in the console. -## Installation - -Event Bus is available in Maven Central. -To include it inside your project, just add the following dependency to your `pom.xml`: - -```xml - - - dev.kske - event-bus-core - 1.1.0 - - -``` - -Then, require the Event Bus Core module in your `module-info.java`: - -```java -requires dev.kske.eventbus.core; -``` - -If you intend to use event handlers that are inaccessible to Event Bus by means of Java language access control, make sure to allow reflective access from your module: - -```java -opens my.module to dev.kske.eventbus.core; -``` - ## Compile-Time Error Checking with Event Bus Proc To assist you with writing event listeners, the Event Bus Proc (Annotation Processor) module enforces correct usage of the `@Event` annotation during compile time. From 39ffb5c82a4f1a66c8ac4ea73478e40d981ecbf7 Mon Sep 17 00:00:00 2001 From: kske Date: Thu, 25 Nov 2021 14:29:06 +0100 Subject: [PATCH 4/5] Fix module-info instructions in README Reflective access has to be allowed from the Event Bus core package to a package in the user's project, not the entire module. Thank you @delvh for noticing this! --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 493d672..7a21f40 100644 --- a/README.md +++ b/README.md @@ -75,10 +75,10 @@ Then, require the Event Bus Core module in your `module-info.java`: requires dev.kske.eventbus.core; ``` -If you intend to use event handlers that are inaccessible to Event Bus by means of Java language access control, make sure to allow reflective access from your module: +If you intend to use event handlers that are inaccessible to Event Bus by means of Java language access control, make sure to allow reflective access to your package for Event Bus: ```java -opens my.module to dev.kske.eventbus.core; +opens my.package to dev.kske.eventbus.core; ``` ## Polymorphic Event Handlers From 5a6d8bcf3592b7f0812181290ee13b78e4a45bba Mon Sep 17 00:00:00 2001 From: kske Date: Thu, 25 Nov 2021 14:34:13 +0100 Subject: [PATCH 5/5] Rename EventBus#printExecutionOrder(Class) to debugExecutionOrder The method doesn't print anything, but rather returns a string containing the debug information. --- README.md | 2 +- .../src/main/java/dev/kske/eventbus/core/EventBus.java | 2 +- .../src/test/java/dev/kske/eventbus/core/DispatchTest.java | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7a21f40..de0d376 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,7 @@ In more complex setups, taking a look at the event handler execution order can b Event Bus offers a method for this purpose which can be used as follows: ```java -System.out.println(EventBus.getInstance().printExecutionOrder(SimpleEvent.class)); +System.out.println(EventBus.getInstance().debugExecutionOrder(SimpleEvent.class)); ``` Then, the execution order can be inspected in the console. diff --git a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java index 42060b7..02cf156 100644 --- a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java +++ b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java @@ -381,7 +381,7 @@ public final class EventBus { * @return a human-readable event handler list suitable for debugging purposes * @since 1.2.0 */ - public String printExecutionOrder(Class eventType) { + public String debugExecutionOrder(Class eventType) { var handlers = getHandlersFor(eventType); var sj = new StringJoiner("\n"); diff --git a/event-bus-core/src/test/java/dev/kske/eventbus/core/DispatchTest.java b/event-bus-core/src/test/java/dev/kske/eventbus/core/DispatchTest.java index 250fc26..07b6db7 100644 --- a/event-bus-core/src/test/java/dev/kske/eventbus/core/DispatchTest.java +++ b/event-bus-core/src/test/java/dev/kske/eventbus/core/DispatchTest.java @@ -45,13 +45,13 @@ class DispatchTest { } /** - * Tests {@link EventBus#printExecutionOrder(Class)} based on the currently registered handlers. + * Tests {@link EventBus#debugExecutionOrder(Class)} based on the currently registered handlers. * * @since 1.2.0 */ @Test void testPrintExecutionOrder() { - String executionOrder = bus.printExecutionOrder(SimpleEvent.class); + String executionOrder = bus.debugExecutionOrder(SimpleEvent.class); System.out.println(executionOrder); assertEquals( "Event handler execution order for class dev.kske.eventbus.core.SimpleEvent (3 handler(s)):\n"