Event handlers are configurable scripts that are triggered when a corresponding event is triggered. They can run synchronously with the trigger or asynchronously. When the script is run synchronously, it has the capability of completely interrupting the process that triggered it, resulting in a rollback of any updates that have not yet been flushed to the target. If the script is run asynchronously, this interruption doesn’t occur because the asynchronous script is guaranteed to run after the completion of the initiating process.
Event objects are available on context.event object within scripts.
This document discusses global event handlers. These behave like functions
that are not members of an object instance - so there is no access to a this
pointer or equivalent. There are two other types of event handlers which are
listed below.
Event handlers can also be defined within classes definitions. These handlers are triggered on the target of the event object associated with the target’s class or any super class of the target’s class. These handlers have access to the “this” keyword (or equivalent), which is set to the event target. See Class Event Handlers to learn more about class level events.
Event handlers can be registered within scripts using api.events.handle. This results in an event handler registration that becomes permanent within the application and survives requests and even redeployments. These handlers can be created and deleted as needed. Any number of dynamic event handlers can be registered and these can be configured to handle both internal events and custom events that were raised through api.events.raise.
[com.appirator.core.]reflect.EventHandler
extends [com.appirator.core.]reflect.ModuleScriptable
extends [com.appirator.core.]reflect.ModuleNamed
extends [com.appirator.core.]Object
parent [com.appirator.core.]reflect.Module
events
An array of the event names that this event handler should capture.
mode optional
The concurrency mode, either SYNC or ASYNC. By default event handlers are ASYNC. Synchronous event handlers are triggered in the same thread as the initiating process and have the capability consequently to interrupt that process if an exception is thrown. Asynchronous event handlers run asynchronously and are guaranteed to be triggered after the completion of the initiating process. Exceptions thrown during the run of the script do not affect the initiating process, nor do the affect any other event handler that happens to be triggered by the same event.
name optional (when using Git sync)
The name of the event handler in its associated module. This is taken from the file name by default if the event handler is being imported as a file. It can be prefixed with the path name of the file when imported as a file where the path segments are separated with a dot. Similarly, if created object over a REST interface dot notation is permitted. This must be unique within the module.
script
The script to be run. This should be in the same language as the associated module.
[PostAccountCreationNotifier.hdl.yaml]
name: PostAccountCreationNotifier
events:
- com.appirator.account.Account.CREATE
mode: ASYNC
script: >
() => {
import('notification').then(module => {
module.notify(event.object, 'AccountCreated');
});
}