ColdBox interceptor example
I have been using ColdBox for quite some time but the other day I decided to step out of my comfort zone and try to learn some new things about the framework. Interceptors are a feature of ColdBox that look really interesting but I have never looked into so I thought it would be a good time to check it out.
Quoting the documentation on the Wiki, interceptors are “ to increase functionality for applications and framework alike, without touching the core functionality or events, and thus encapsulating logic into separate decoupled objects.” This functionality can be bound to specific events in a request cycle and even create custom interception points and call those events with the announceInterception() method. Awesome stuff!
One of my first open-sourced projects I did was a utility called WhosOnCFC and I thought it would be a good starting point for my first ColdBox interceptor. When a browser views the web site it checks an internal list of the known clients and if the client is not known it tracks some basic information on the browser such as IP address, current URL and the user agent. On subsequent page loads it will update the current URL and time. Traditionally this would be handled in Application.cfc in onRequestStart() so lets see how to handle this with a ColdBox interceptor.
This is the basic layout for an interceptor. The configure() method is required but as this is a very simple interceptor no additional configuration is needed so it is empty..
Next is the afterAspectsLoad() method which is triggered once the application has started. It is ColdBox’s approximation of onApplicationStart(). This is where the instance of WhosonTracker is created and set in the Object Cache Manager so it will persist between requests.
Finally there is the preProcess() method which will execute on every page load. The method will grab the instance of the tracker from the OCM and call the trackHit() method which is where the magic happens.
If you were writing your own interceptor you could bind to as many or as few events as you like. These two events will do for this example.
Now lets take a look at the component that will be doing the work for us, WhosonTracker.cfc. Basically, when initialized we create an array that will store our client data. The trackHit() method is our meat and potatoes. Every request it will check to see if the client is known and either create a new client or update the current clients information. It will also clear out any clients that have not updated in the last five minutes.
There is also a getData() method that our handlers/services can use to get a listing of clients we can output.
Finally we need to register our interceptor with ColdBox so it is executed. Once the application is reloaded the new interceptor should be called on every page request..
As you can see it is easy to create your own interceptors. I did some searching while trying to figure things out and there is tons of documentation out there and a few recipes on the ColdBox site for creating your first interceptor, but it did not really walk you through the process. Hopefully someone may find this useful.
The full code listing is available here: https://github.com/robertz/coldbox-salsa
There you can find some additional code such as the handlers and views to output the data. My development server removes the /index.cfm from the URL by default so if your server does not support SES URLs, edit /config/Routes.cfm on line 15 and add /index.cfm to setBaseURL().