Event Handler
Event handlers are a very lightweight method of providing a means to adjust tags and custom functions in document templates where you need to persist data from one call to the next, such as a running total across calls to a custom function.
The WindwardEventHandler that comes with the engine has a getData and setData methods for storing data inside of a hash map that will persist for the duration of the report creation.
An event handler can be assigned to each (Process)Report object before it is run. The event handler is an object that extends or is the WindwardEventHandler Class. This object is accessed in two places.
- Before each tag is processed, the event handler method for tag pre-processing is called. This method can change the attributes for the tag (including the select).
- If a custom function implementation includes the method void setMacroState (IMacroState state), then this will be passed an IMacroState object, which includes a pointer to the WindwardEventHandler object, before each call to a custom function.
You may only pass a single event handler to a (Process)Report object. If you have multiple operations you wish to perform, you need to place all that in the single event handler.
The engine treats the event handler object as a singleton read-only object. The engine will not change any data in the object. And it passes the same object throughout the processing of the report so changes you make to data in the object are persisted into subsequent calls.
Please note that event handlers are not a means to provide data to the report. If you wish to do that, write a data source. For more information, see the Data Source article.
If you implement void setMacroState (IMacroState state) in a custom function, verify that the object returned by state. getEventHandler() is the class you expect before casting it. It is possible that someone may assign an object from a totally different class as the event handler and call your custom function.
Architecture
Event handlers are created by you and then assigned to a (Process)Report after you create it and before you run it. You can pass the same event handler object to multiple reports, but it is unlikely that you will ever want to do that as it will be mixing the object’s state across several reports.
The event handler object is called as each tag is processed when merging the data from tags in the template into the final report.
It will first call WindwardEventHandler processTag() to give you the opportunity to override the tag’s attributes. You cannot tell the engine to not process a tag, but you can set the select attribute to be a value which is the equivalent of not processing the tag (such as “’” for the out tag). Keep in mind that you can cause the engine to throw an exception if you delete required properties or provide illegal values for properties.
If you change the tag attributes, if that tag is processed again (due to being inside a forEach loop), those changes will persist to subsequent uses of the tag.
Second, during the processing of the select in a tag, if that select includes custom functions that implement void setMacroState (IMacroState state), then the engine will provide the event handler object and a copy of the tag’s attributes to the custom function.
In this second case, while the custom function can change data in the event handler object, the tag attributes are read-only. The custom function can change the attributes as Java provides no way to define them as read only, but the changes will not be persisted to the tag.
The custom functions are processed in the order they are evaluated in the select for the tag.
