Add ExceptionWrapper documentation

This commit is contained in:
Leon Hofmeister 2022-01-08 16:44:49 +01:00
parent 84ae42b44f
commit adbcc64e94
Signed by: delvh
GPG Key ID: 3DECE05F6D9A647C

View File

@ -183,14 +183,37 @@ private void onDeadEvent(DeadEvent deadEvent) { ... }
### Detecting Exceptions Thrown by Event Handlers ### Detecting Exceptions Thrown by Event Handlers
When an event handler throws an exception, an exception event is dispatched that wraps the original event. When an event handler throws an exception, an exception event is dispatched that wraps the original event.
A exception handler is declared as follows: An exception handler is declared as follows:
```java ```java
private void onExceptionEvent(ExceptionEvent ExceptionEvent) { ... } private void onExceptionEvent(ExceptionEvent ExceptionEvent) { ... }
``` ```
Both system events reference the event bus that caused them and a warning is logged if they are unhandled. Both system events reference the event bus that caused them and a warning is logged if they are unhandled.
#### Yeeting Exceptions Out of an Event Handler
In some cases, a warning about an `Exception` that was thrown in an event handler is not enough, stays unnoticed, or an exception should be catched explicitly.
Event Bus explicitly dispatches no `ExceptionEvent` when an `ExceptionWrapper` exception is thrown and instead simply rethrows it.
`ExceptionWrapper` is an unchecked exception that (as the name says) simply wraps an exception that caused it.
This means the following is possible and results in a normal program exit:
```java
@Event(String.class)
void onString() {
throw new ExceptionWrapper(new RuntimeException("I failed!"));
}
void helloStackTrace() {
EventBus.getInstance().registerListener(this);
try {
EventBus.getInstance().dispatch("A string!");
System.exit(-1);
} catch(ExceptionWrapper e) {
e.getCause().printStackTrace();
System.exit(0);
}
}
```
### What About Endless Recursion Caused By Dead Events and Exception Events? ### What About Endless Recursion Caused By Dead Events and Exception Events?
As one might imagine, an unhandled dead event would theoretically lead to an endless recursion. As one might imagine, an unhandled dead event would theoretically lead to an endless recursion.