Understanding Blackstone Application Events

The new application event mechanism (planned for Blackstone) provides powerful new functionality to ColdFusion developers. Lots of you have asked about this feature since it was first mentioned in the MAX ColdFusion BOF (and then blogged in my BOF report), and so a basic overview is in order. Here goes.
ColdFusion currently supports two events, request start and request end. In other words, ColdFusion allows you to write code that is automatically executed before and after every request. Request start code is put into a file named Application.cfm, and request end code is put into a file named OnRequestEnd.cfm (and yes, Application.cfm is a bad name, OnRequestStart.cfm would have been more accurate, but oh well).
In Blackstone we plan to support these same two events, and some additional ones. Here is the list, and a brief example of how you could use them:
OnRequestStart: This is functionally the same as Application.cfm now, this is where you would place any code that needs to be executed before each request. An example of this might be checking to see if a user is logged in or not.
OnRequestEnd: This is functionally the same as OnRequestEnd.cfm now, and this is used for code to be executed after each request. This is sometimes used for debugging, to grab entire scopes, perhaps logging them for subsequent analysis.
OnApplicationStart: This is a new event, it is executed when an application first starts, and will not execute again unless the application times out, the server is restarted, or an explicit OnApplicationStart call is made. This is where you will typically initialize data in the APPLICATION scope. Look at your current Application.cfm, any code wrapped in a block likely belongs in OnApplicationStart.
OnApplicationEnd: Another new event, this one is executed when an application times out, or upon graceful server shutdown. This will likely be an infrequently used event, and it too can be used for debugging, logging, saving accumulated totals and stats to disk, and more.
OnSessionStart: This one is new too, and is the most requested new event. This one executes whenever a new SESSION is created, and is therefore the ideal place to store user preferences, initialize shopping carts, and more.
OnSessionEnd: Also new, and the counterpart to OnSessionStart, this one executes when a session times out. This can be used to save shopping cart contents to disk, for example, so that when users return later they can pick up where they left off. It can also be used to keep track of incomplete transactions, perhaps users who put items into a shopping cart and left without ever checking out, code in this event can track and log that.
OnRequest: The last new event, this one gets executed for every request in lieu of the actual request. If present, requests are processed by OnRequest code which can, if wanted, then execute the original request. For example, if you wanted to trap all requests from a known IP address, sending them to another URL, this would be a good place for it. If you wanted to display a “we are down between 4 and 5 am” notice, this is where you could do it. And if you wanted to process request generated output (perhaps to use compression or to strip whitespace) you could do that here too.
Of course, the old style Application.cfm files will still be supported, but with all of this new power, why would you even want to use them? πŸ™‚

12 responses to “Understanding Blackstone Application Events”

  1. Oliver Merk Avatar
    Oliver Merk

    Very cool. So will we literally create templates called "OnSessionStart.cfm", etc?
    And will CF look up the directory tree until it encounters these files as with Application.cfm?

  2. Ben Forta Avatar
    Ben Forta

    Oliver, I did not discuss file naming or syntax at all, yet. πŸ™‚

  3. Tim Avatar

    All of these sound great. But what about a "onServerStart". Many applications cache a large amount of data in the application scope. But this cache isn’t built until the first hit to the application. OnServerStart could be used to initialize all the applications on a server when it is first turned on or restarted.

  4. Ben Forta Avatar
    Ben Forta

    It is unlikely that onServer events will make it in for now. Those were on the spec, but the implementation for those needs to be different (they cannot really be tied to applications the way other events are). They are still on the todo list, but likely not for Blackstone.

  5. Aidan Sherring Avatar
    Aidan Sherring

    This will be extremely useful. On about a OnError event. There are many things you can’t do with the CFError tag and you can’t try/catch everything. It would be useful to have an event fire when an error happens. That way an admin could write a script to do whatever he chooses with the error.

  6. Ben Forta Avatar
    Ben Forta

    There is an OnError too, sorry, can’t believe I missed that one. So yes, OnError is planned too.

  7. Jim Avatar

    Ben. Stop teasing us! πŸ™‚
    Almost daily I run into things where I go "man this will be so much easier with Blackstone" …

  8. Ben Forta Avatar
    Ben Forta

    Jim, but it’s such fun! πŸ˜‰

  9. Greg Avatar

    Hope the Session events will work when utilizing J2EE sessions too.

  10. Scott Barnes Avatar
    Scott Barnes

    heh I made a post about this in August, and got cained for it "as if you need events in CFMX" etc.
    Can’t wait for Blackstone to go public.

  11. Greg Avatar

    What do you mean by "this"? Where you referring to my comment or something else?

  12. Scott Barnes Avatar
    Scott Barnes

    No, i meant the whole events and coldfusion. I made a post on MossyBlog about it and I got a few passive responses but when I made posts elsewhere and @ CFUG meetings i got a bit of public backlash and clueless looks.
    I thought maybe i’m overshooting or something like that.. then when i heard its now got it in place, i was excited yet i felt like walking up to those people and going "hah, see told ya so! – others wanted it aswell! "

Leave a Reply