Merge pull request 'Document Latest Features in README' (#27) from f/improved-readme into develop

Reviewed-on: https://git.kske.dev/kske/event-bus/pulls/27
Reviewed-by: delvh <leon@kske.dev>
This commit is contained in:
Kai S. K. Engelbart 2021-11-26 13:54:58 +01:00
commit 11860d1469
Signed by: Käfer & Engelbart Git
GPG Key ID: 70F2F9206EDC1FCE
3 changed files with 48 additions and 25 deletions

View File

@ -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. 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
<dependencies>
<dependency>
<groupId>dev.kske</groupId>
<artifactId>event-bus-core</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies>
```
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 to your package for Event Bus:
```java
opens my.package to dev.kske.eventbus.core;
```
## Polymorphic Event Handlers ## 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. 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.
@ -94,6 +121,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. 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 ## 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. 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.
@ -159,32 +198,16 @@ 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. To avoid this, system events never cause system events and instead just issue a warning to the logger.
## Installation ## Debugging
Event Bus is available in Maven Central. In more complex setups, taking a look at the event handler execution order can be helpful for debugging.
To include it inside your project, just add the following dependency to your `pom.xml`: Event Bus offers a method for this purpose which can be used as follows:
```xml
<dependencies>
<dependency>
<groupId>dev.kske</groupId>
<artifactId>event-bus-core</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies>
```
Then, require the Event Bus Core module in your `module-info.java`:
```java ```java
requires dev.kske.eventbus.core; System.out.println(EventBus.getInstance().debugExecutionOrder(SimpleEvent.class));
``` ```
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: Then, the execution order can be inspected in the console.
```java
opens my.module to dev.kske.eventbus.core;
```
## Compile-Time Error Checking with Event Bus Proc ## Compile-Time Error Checking with Event Bus Proc

View File

@ -381,7 +381,7 @@ public final class EventBus {
* @return a human-readable event handler list suitable for debugging purposes * @return a human-readable event handler list suitable for debugging purposes
* @since 1.2.0 * @since 1.2.0
*/ */
public String printExecutionOrder(Class<?> eventType) { public String debugExecutionOrder(Class<?> eventType) {
var handlers = getHandlersFor(eventType); var handlers = getHandlersFor(eventType);
var sj = new StringJoiner("\n"); var sj = new StringJoiner("\n");

View File

@ -45,13 +45,13 @@ public 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 * @since 1.2.0
*/ */
@Test @Test
public void testPrintExecutionOrder() { public void testDebugExecutionOrder() {
String executionOrder = bus.printExecutionOrder(SimpleEvent.class); String executionOrder = bus.debugExecutionOrder(SimpleEvent.class);
System.out.println(executionOrder); System.out.println(executionOrder);
assertEquals( assertEquals(
"Event handler execution order for class dev.kske.eventbus.core.SimpleEvent (3 handler(s)):\n" "Event handler execution order for class dev.kske.eventbus.core.SimpleEvent (3 handler(s)):\n"