Learning ColdFusion 9: Application.cfc OnCFCRequest Event Handler For CFC Requests

Earlier this week, Ray Camden blogged about ColdFusion 9's new onCFCRequest() event handler method in Application.cfc. If you look at the Application.cfc reference guide in the ColdFusion 9 documentation, you'll notice that it is not there at all (so far the CF9 docs have been extremely under whelming). As such, there are a lot of questions that I have about the use of the OnCFCRequest() event handler and very few answers. So, I figured it was time to take what Ray has shown us and start performing some experiments.

First thing's first, let's just get comfortable with the basic structure of the OnCFCRequest() event handler. As Ray mentioned, OnCFCRequest() takes three arguments:

• Component: The name/path of the ColdFusion component requested by the user.
• MethodName: The name of the method requested by the user for execution.
• MethodArguments: The argument collection (struct) sent by the user in the request.

That's what it takes, but what does it return? From what I can gather, the ReturnType of the OnCFCRequest() method should be VOID just like its OnRequest() counter-part. Returning a value from this method does not seem to play any part in what actually gets returned in the page response. To return a value, you either have to output it within the method body, or stream it back via CFContent (covered later).

Here's what a simple Application.cfc component using OnCFCRequest() might look like:

Application.cfc

Notice that the OnRequest() and the OnCFCRequest() event handlers live side-by-side. We don't need to do anything special in order to get them to play nice. As Ray demonstrated in his blog post, calls made to remote CFCs will simply ignore OnRequest() and trigger OnCFCRequest(). For our initial demonstration purposes, my OnCFCRequest() outputs the query string, URL, and ARGUMENTS Scopes. This way we, we can see how ColdFusion pipes the request into the event handler method.

Now, let's set up a really simple ColdFusion component with a remote access method for testing:

Service.cfc

All this Service.cfc does is supply a remote method, GetGirl() which takes a girl's name, wraps it up in a struct, and returns it. If called remotely, I have defaulted the ReturnFormat to use JSON conversion.

With our simple Application.cfc / OnCFCRequest() event handler and Service.cfc remote object set up, let's make some page requests. First, I am going to call a simple REST-based request:

Service.cfc?method=getGirl&name=Tricia&returnformat=json

When we run this request, we get the following page output:

The first thing we can take away from this is that the call to the actual remote method never executed. The page request was piped into the OnCFCRequest() event handler; but, just as with the OnRequest() event handler, if we don't then explicitly call the requested component and method, it gets ignored. The next thing we can see is that ColdFusion appropriately separates the URL variable from the method arguments. Meaning, it doesn't send things like Method and ReturnFormat as part of the requested method's argument collection.

Seeing this, I wondered what would happen if we passed in "WSDL" with the query string:

Service.cfc?wsdl

Normally, this would present us with the Web Service Definition XML. But, when we run this, we get the following response:

It looks like WSDL requests are treated just like any other requests. This does not bode well for the use of OnCFCRequest() in conjunction with SOAP-based web service calls. My guess is that this kind of Application.cfc architecture is not going to play well with any kind of request that uses behind-the-scenes ColdFusion auto-wiring. Things like SOAP requests and AMF requests will probably fail (or be ignored - I am not sure how AMF makes requests).

That said, the rest of this exploration will stick to REST-based requests in which what you see is what you get in the response. Of course, up until now, we really haven't seen any response; or rather, we haven't seen the response expected by the intent of our request URL - all we've seen is the CFDump output we have in our OnCFCRequest() event handler. So, how do take our request, translate it to a CFC method execution, and then return that value?

I actually talked about this in depth when demonstrating how to handle errors in remote API calls in ColdFusion 8. The same principle applies: we need to make the CFC request, check the return format, perform any transformations manually, and then return it. To demonstrate this, I have beefed up the OnCFCRequest() event handler to follow this logic:

OnCFCRequest() Event Handler

As you can see, the OnCFCRequest() event handler takes the request, creates the CFC, calls the method, and then transforms and returns the result using CFContent. Now, when we call this URL:

Service.cfc?method=getGirl&name=Tricia&returnFormat=json

... we get this JSON response:

{"NAME":"Tricia"}

And, when we call this URL:

Service.cfc?method=getGirl&name=Tricia&returnFormat=wddx

... we get this WDDX response:

<wddxPacket version="1.0">
<header/>
<data>
<struct><var name="NAME"><string>Tricia</string></var></struct>
</data>
</wddxPacket>

That seems pretty straight forward, but I know what you're thinking - OK, so we've now re-created the inherent functionality of ColdFusion, but we've added a LOT of overhead. How can that be good?

Excellent question, and one that I certainly asked myself. With the overhead of the manually execution comes some advantages. Namely, better instantiation and caching. Let's take a look at that quickly.

API Component Instantiation And Caching

Because the CFC request is be routed through our OnCFCRequest() event handler, the target ColdFusion component doesn't get instantiated until we create it manually. And, because we are doing manual instantiation, we get two benefits: we can use an Init() method on our API objects to inject any required dependencies (without breaking encapsulation!!) and we can cache the CFC instance so we don't have to create it again.

In the following example, we will caching the target CFC in our APPLICATION. You'll notice that I'm calling Init() on the Service.cfc. I'v added it, but it doesn't do anything so I won't bother showing the code:

Application.cfc

Notice that I've added an OnApplicationStart() event handler so that I can create our remote object cache:

application.apiCache

This struct will take component instances keyed using their path (as defined by the OnCFCRequest() method argument). Then, once inside the OnCFCRequest() event handler, I check to see if the API object already exists in the cache. If it does not, then I instantiate it and cache it. Once that is done, every subsequent remote CFC request to that object can simply pull the existing instance out of the cache.

OnMissingMethod() Functionality

When I first started playing around with this, I thought, Hey, because we are manually instantiating the target CFCs in our remote calls using OnCFCRequest(), we can now take full advantage of ColdFusion's OnMissingMethod() functionality introduced in ColdFusion 8. After all, because we are dealing with a true instance of the target component from within the ColdFusion application framework, requested a method that doesn't exist, should fire the OnMissingMethod() handler (if it exist).

So, I started to wire this all together. First, I went into my Service.cfc and adding an OnMissingMethod() handler that would simply return an array of the result of calling GetGirl() - I was planning to call "GetGirls" in the demo:

Service.cfc

Notice that it merely wraps the GetGirl() result in an implicit array [].

Then, I went into my OnCFCRequest() method and updated it to work with OnMissingMethod() events. Because we are getting the ReturnFormat from the target method, we had to add that to our URL.ReturnFormat parameterization logic:

OnCFCRequest() With OnMissingMethod Logic

Once I had this wired up, I got super excited and called the following URL:

Service.cfc?method=getGirls&name=Tricia

Because "getGirls" does not exist, the OnCFCRequest() event handler should have routed the request through the OnMissingMethod() method on the Service.cfc (implicitly) and returned and array. But, instead, what I got was this ColdFusion error:

The method getGirls was not found in component Service.cfc.

WHAT?!?!?! When I saw this, I almost blew my top (I had spend 15 minutes wiring this all up and debugging the parts). It doesn't work? Are you kidding me?

It appears as if ColdFusion is actually checking the target component meta data to see if the API request can be made before it even passes it off to the OnCFCRequest() event handler. This is clearly and blatantly a bug in the Application.cfc framework as it completely defeats the intent of have request-handlers in the Application.cfc! If the target file exists (Service.cfc), the surrounding data (ex. method name parameter) should be completely irrelevant - it should be up to the request handler to deal with that scenario.

Overall, I think the OnCFCRequest() event handler is interesting, but I don't know how useful it actually is. Yes, we can now cache our target API objects, but is the minor instantiation cost of a thin API layer worth the overhead of all the manual instantiation and caching? Maybe it is, maybe it isn't. If they can fix the serious OnMissingMethod() bug, then there might be some more use. For now, however, it seems that the best request-handling update is the fact that the OnRequest() event method will not be triggered for CFC-based requests.

What Other People Are Searching For

[ local search ] coldfusion 9 examples
[ local search ] coldfusion 9 tutorials

You Might Also Be Interested In: