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
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
private void onExceptionEvent(ExceptionEvent ExceptionEvent) { ... }
```
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?
As one might imagine, an unhandled dead event would theoretically lead to an endless recursion.