Document Latest Features in README #27

Merged
kske merged 6 commits from f/improved-readme into develop 2021-11-26 13:54:58 +01:00
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;
kske marked this conversation as resolved Outdated
Outdated
Review

opens works for modules as well?
I thought it should have been opens my.package to dev.kske.eventbus.core...

`opens` works for modules as well? I thought it should have been `opens my.package to dev.kske.eventbus.core`...
Outdated
Review

This seems to be wrong actually. I will change it accordingly.

This seems to be wrong actually. I will change it accordingly.
```
## 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));
kske marked this conversation as resolved Outdated
Outdated
Review

Something looks strange here:
a) if printXY prints directly, the syso part is unneeded.
b) if printXY only returns the result, then the function should be renamed.

Something looks strange here: a) if `printXY` prints directly, the `syso` part is unneeded. b) if `printXY` only returns the result, then the function should be renamed.
Outdated
Review

The code itself is correct, but I agree that the name of the method can be misleading. What would you call a method that formats the execution order in a human-readable way as a string, but doesn't print it. Printing it to sysout directly seemed to specific to me, as some applications would prefer using a logger instead.

The code itself is correct, but I agree that the name of the method can be misleading. What would you call a method that formats the execution order in a human-readable way as a string, but doesn't print it. Printing it to sysout directly seemed to specific to me, as some applications would prefer using a logger instead.
Outdated
Review

generateExecutionOrder?
getDebugInformation?
createExecutionOrderString?
executionOrderAsString?
getExecutionOrderAsString?

`generateExecutionOrder`? `getDebugInformation`? `createExecutionOrderString`? `executionOrderAsString`? `getExecutionOrderAsString`?
``` ```
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"