We have already seen in our previous section all the events that are announced by WireBox, but how do we listen? There are two ways to build WireBox listeners because there are two modes of operations, but the core is the same.
Listeners are simple CFCs that must create methods that match the same name of the event they want to listen to.
If you are running WireBox within a ColdBox application, listeners are Interceptors and you declare them and register them exactly the same way that you do with normal interceptors.
These methods can take up to two parameters depending on your mode of operation (standalone or ColdBox). The one main difference between pure Wirebox listeners and ColdBox interceptors are that the configure
method for the standalone WireBox is different.
WireBox also sports a very nice event model that can announce several object life cycle events. You can listen to these events and interact with WireBox at runtime very easily, whether you are in standalone mode or within a ColdBox application.
Note If you are within a ColdBox application, you get the benefit of all the potential of ColdBox Interceptors and if you are in standalone mode, well, you just get the listener and that's it.
Each event execution also comes with a structure of name-value pairs called interceptData
that can contain objects, variables and all kinds of data that can be useful for listeners to use. This data is sent by the event caller and each event caller decides what this data sent is. Also, remember that WireBox also can be ran with a reference to CacheBox, which also offers lots of internal events that you can tap into. So let's start investigating first the object life cycle events.
WireBox's offers a wide gamut of life cycle events that are announced at certain points in execution time. Below are the current events announced by the Injector wirebox.system.ioc.Injector
.
Note Please see our CacheBox documentation to see all of CacheBox's events.
Event
Data
Description
afterInjectorConfiguration
injector : The calling injector reference
Called right after the injector has been fully configured for operation.
beforeInstanceCreation
mapping : The mapping called to be created
Called right before an object mapping is built via our internal object builders or custom scope builders.
afterInstanceInitialized
mapping : The mapping called to be created
Called after an object mapping gets constructed and initialized. The mapping has NOT been placed on a scope yet and no DI/AOP has been performed yet
afterInstanceCreation
mapping : The mapping called to be created
Called once the object has been fully created, initialized, stored, and DI/AOP performed on it. It is about to be returned to the caller via its getInstance() method.
beforeInstanceInspection
mapping : The mapping that is about to be processed.
Called whenever an object has been requested and its metadata has not been processed or discovered. In this interception point you can influence the metadata discovery.
afterInstanceInspection
mapping : The mapping that is about to be processed.
Called after an object mapping has been completely processed with its DI metadata discovery. This is your last chance to change or modify the DI data in the mapping before it is cached.
beforeInjectorShutdown
injector : The calling injector reference
Called right before the Injector instance is shutdown.
afterInjectorShutdown
injector : The calling injector reference
Called right after the Injector instance is shutdown.
beforeInstanceAutowire
injector : The calling injector reference
Called right after the instance has been created and initialized, but before DI wiring is done.
afterInstanceAutowire
injector : The calling injector reference
Called right after the instance has been created, initialized and DI has been completed on it.
Please note the configure()
method in the standalone listener. This is necessary when you are using Wirebox listeners outside of a ColdBox application. The configure()
method receives two parameters:
injector
: An instance reference to the calling Injector where this listener will be registered with.
properties
: A structure of properties that passes through from the configuration file.
As you can see from the examples above, each Listener component can listen to multiple events. Now you might be asking yourself, in what order are these listeners executed in? Well, they are executed in the order they are declared in either the ColdBox configuration file as interceptors or the WireBox configuration file as listeners.
Caution Order is EXTREMELY important for interceptors/listeners. So please make sure you order them in the declaration file.
Argument
Type
Execution Mode
Description
interceptData
struct
standalone-coldbox
The data structure passed in the event
So let's say that we want to listen on the beforeInjectorShutdown and on the afterInstanceCreation event in our listener.
Argument
Type
Execution Mode
Description
event
coldbox.system.web.context.RequestContext
coldbox
The request context of the running request
interceptData
struct
standalone-coldbox
The data structure passed in the event
buffer
coldbox.system.core.util.RequestBuffer
ColdBox
A request buffer object for producing elegant content in ColdBox applications
rc
struct
coldbox
Reference to the rc
scope
prc
struct
coldbox
Reference to the prc
scope