Stake Five

In my last few posts, I looked at the mechanisms CF8 provides to get data into the browser. Just getting data is not enough, of course - you still need to plug that data into elements in the browser’s HTML DOM tree so that is is made visible to users, allowing them to view and interact with it. This calls for JavaScript skills, and possibly the use of toolkits like jQuery or Prototype to ease the task. Such applications can be extremely powerful and interactive, but do require a lot of custom JavaScript code.

Your average Web 1.0 application performs tasks like this on the server - hence the plethora of templating languages, designed to allow programmers to plug data into HTML markup. ColdFusion was the first, of course, and as we like to modestly claim, still the best! ;)

It seems inevitable that someone would come up with the idea to combine these two approaches, asynchronously fetching markup from the server, and plugging that markup into the HTML DOM tree in the browser. It’s a pretty neat idea - let the server process the template for a given fragment of HTML, which allows programmers to code in a familiar server-side templating language, use AJAX to fetch that markup fragment, and push it into the browser’s HTML DOM tree. Given the need for a catchy Web 2.0 acronym, the technique has come to be called AHAH, short for Asynchronous HTML And HTTP, pronounced “a-ha!” or perhaps “ah! ah!” - I’ll leave the choice to you, dear reader.

CF8 provides support for AHAH in a number of different ways - with the ColdFusion.navigate() JavaScript API, the various AJAX “container” tags (CFDIV, CFLAYOUTAREA, CFWINDOW and CFPOD), and the AjaxLink() and AjaxOnLoad() built-in functions. The “container” tags are so called since they act as containers for HTML markup, allowing the contained markup to swapped out for new markup fragments fetched from the server. In my next few posts, I’ll talk about the functionality these tags and functions offer, and how you can use them in your CF8 AJAX applications.

So far, I’ve discussed templating on the server, and using custom JavaScript to plug data into the HTML DOM tree on the browser. There is also a third approach - templating on the browser. To date, the only framework that I know of which accomplishes this is Spry. So here’s another way to build your AJAX applications - use Spry JSON datasets in conjunction with CF8 JSON web services to pull data into the browser. But more on that later…

Tim Bray, whose work I admire deeply, is being published along with many other great programmers in Beautiful Code. Follow the link to the O’Reilly site to get a sample chapter, “Finding Things”, which happens to be Tim Bray’s, on search, from small to big.

I like the idea of this book, being as it is more about the art and craft of computer programming, rather than the science.

When I was at Aztec Software, we used to have short half-day courses that were run on a volunteer basis. Amongst these courses was one called, if memory serves right, “Industrial Strength Programming”. The first task students were given was to compile the Apache web server - I love courses like this, since they teach by real-world example. In order to get the compile working, a student was forced to go through, and understand, at least a little bit, the Apache makefile, and in the process, encounter some of the decisions the Apache web server team made while designing their build process. We learn by doing, and we learn best when we see how someone else has solved similar problems, understand what judgment calls they had to make, and so gain greater skill in the art and craft of programming.

Wouldn’t it be great if there were college-level computer courses that dissected, let’s say, Apache Tomcat, or PostgreSQL, and so taught students how theoretical computer science concepts could be applied in real projects, and what trade-offs had to be made? Or (nudge, nudge) if someone were to take apart ColdSpring, MG, Fusebox or BlogCFC, explain how they’re structured internally, what design decisions were taken, and why?

We do this every day, in a smaller way, through our blogs and technical articles, but I do believe that a larger, structured course in the art and craft of programming could prove invaluable. This idea first came up a few years ago, in conversation with a very good friend of mine, and one of the most creative technical minds I know, Ramesh Srinivasraghavan, now Head of Research and Development at Aztec Software.

Open source provides invaluable material to learn from, in the form of source code. But that is only half the story - the knowledge and opinions that guide the design of successful software projects are more valuable by far.

Beautiful Code is definitely going on my reading list - as soon as I have some time to read! At the moment, I’m in the throes of preparations for our move to Berkeley, and, of course, tying neat little ribbons on Scorpio code in preparation for the final release.

For reasons beyond my ken, it’s cheaper on Amazon than direct from O’Reilly. Read it!

Now that I’ve covered the server-side JSON support we have in place, it’s time to talk about something a little different - the client-side tools that CF8 provides to leverage the stuff we’ve put in on the server.

If you’re a CF developer, you’d have to be encased in carbonite not to have heard that CF8 adds a slew of new tags and functions to help you build AJAX applications. The first of these to be built was the CFAJAXPROXY tag.

Once automatic JSON<->CFML serialization and deserialization was built into CF’s remote CFC invocation layer, the next logical step was to provide a mechanism that would allow invocation of CFC functions remotely from a web browser in the simplest manner possible. The easy way out would have been to just write a JavaScript function that works like CFINVOKE, perhaps something like this:

ColdFusion.invoke(<Path to CFC>, <Function>, <Arguments>)

We did consider it, but it just didn’t feel natural enough… Continue Reading »

In my last post, I looked at the new JSON functions available in ColdFusion 8, and showed how they could be used to consume JSON web services. Today I’ll look at how CF8 lets you expose your applications as JSON web services.

Even with just the CF8 JSON functions, it is easy to create JSON web services - consume arguments from the caller (in the URL or FORM scopes) in JSON format, deserializeJSON() those to CFML types, run your logic on the CFML objects, then serializeJSON() your return type to get the data back to the caller in JSON format. Easy to do, from a CFC or a CFM.

But with our credo of making hard things easy (and easier!) that just wasn’t good enough.

Lost In Translation?

I’ve always liked the notion that the transformation from and to data formats for communication should be independent of application logic. Taking that a step further, I like to think that application designers should not need to worry about data formats (well, not too much, anyway!) - the client of a web service should be able to decide the data format in which it wishes to communicate, depending on its capabilities. Perhaps one client likes to talk SOAP web services, another prefers XML, and, perhaps, is willing to play with WDDX, and yet another chooses to chatter away in JSON. Once an application designer decides that a particular bit of logic should be exposed as a web service, why should it matter what format the data is exposed as?

RESTful Web Services

Before I get into what we’ve done with CF8 in this space, a little background first - did you know you could invoke CFC functions over HTTP? You should - to my mind, it’s one of the coolest things about CF, which I’ve written about before. Here’s how it works:

http://myhost/my/application/callme.cfc?method=echo&input1=yodel&input2=hey

Simple - form a URL to the location of your CFC, and pass it the function to invoke in the method request parameter (URL or FORM scope). Other request parameters are provided to the CFC as arguments. Of course, you have to be sure that the CFC function you’re invoking is marked access=remote, or CF will not allow you to call it remotely, as a web service. By default, the return format is WDDX - CF will automatically serialize the return value from your CFC to WDDX and return that to the caller. Arguments can be provided to the CFC in complex nested CFML types using the special request parameter argumentCollection, which can take a WDDX-formatted string, which must represent a CFML struct, and is deserialized to form the arguments scope for the CFC function to be invoked.

In the currency of the dynamic web, CF makes it simple to expose CFCs as REST web services. If you are planning to design web services into you applications, and don’t know what REST is, you should - REST, or REpresentational State Transfer, outlines a way of thinking about web services architecture using the mechanisms built into HTTP, rather than reinventing the wheel a la SOAP web services. For more see Roy Fielding’s Ph.D. dissertation (Roy Fielding originated the term, relevant chapter here), and for an easier, more fun, introduction, see Duncan Cragg’s REST dialogues. Personally, I’m a huge fan of REST web services - while SOAP has it’s place, I think it really is needlessly bloated and overly complex for the vast majority of use cases it is applied to.

Talking Tongues

Getting back on topic, CF8 introduces the new returnFormat attribute for HTTP invocations of CFC functions, which allows a caller to specify the format of data they’d like to get back. returnFormat supports the following options:

• wddx - the default, return data as WDDX
• json - serialize the return value from the function to JSON and return it
• plain - do nothing with the return value from the function, return it as-is. Note that the plain return format works only for simple types or XML documents. If you try to return a complex type (struct, array, query) with returnFormat=plain, CF will throw an error, since complex types cannot be returned as-is; they must be serialized to a string representation (WDDX or JSON) to transmit over HTTP. Also note that if you’re returning a XML document, you should remember to set the HTTP response content type appropriately - text/xml for most cases, or as appropriate for the particular XML dialect that you’re returning.

Taking my example above, a user who wants a JSON response would modify the URL like so:

http://myhost/my/application/callme.cfc?method=echo&input1=yodel&input2=hey&returnFormat=json

To flesh things out, CF8 can also accept JSON in the argumentCollection request parameter. For instance:

http://myhost/my/application/callme.cfc?method=echo&argumentCollection={"input1":"yodel","input2":"hey"}&returnFormat=json

For completeness, returnFormat is also available as a CFFUNCTION attribute - if you would rather your remote functions had a default other than WDDX you can set it on your functions, and save callers from have to specify it in their requests.

So what’s it good for?

For starters, you can now invoke CFCs directly from AJAX applications - there any any number of AJAX frameworks, including Spry, jQuery and Prototype, which provide support for consuming data from JSON web services. Oh, and lest we forget, CF8 offers up the cfajaxproxy tag to aid in this effort - but more on that later.

Or, if you buy into the “web as a platform” meme (I know I do!), you could choose to expose public JSON web services from your applications, as do del.icio.us, and many others. I particularly like the fact that services such as del.icio.us, built on the backs of their users’ tag gardening activity, open up the data for others to access and do with as they will. Then there’s the it-makes-commercial-sense approach, with companies such as Amazon leading the way - Amazon Web Services provide an astonishing array of functionality (XML rather than JSON, but that’s besides the point), providing pay-as-you-go services, such as S3, and the eCommerce Service, which allows developers to build their own storefronts on top of Amazon’s catalogues.

Think you could be the next Amazon? CF8 makes the technology end of things easier - by a lot - and it certainly doesn’t hurt that CF8 ups the ante on performance to let you operate at Amazon-scale that much more easily.