Prerequisite knowledge
A basic understanding of web technologies is required.
User level: All
Required products


Sample files
Note: This article was created based on the ColdFusion 9 and ColdFusion Builder beta releases. Minor changes in the description and code may be necessary before it can be applied to ColdFusion 9 and ColdFusion Builder.
With so many great technologies being released from Adobe right now, it is hard to pin down just a subset of new features to show off—but using Adobe ColdFusion 9 and Adobe ColdFusion Builder to reinvent SOA is a good place to start!
In this tutorial I will touch on a variety of new opportunities that exist for developers in ColdFusion 9 to provide services to distributed applications written in diverse languages and delivered across multiple devices. Along the way, you'll also get a better understanding of how using ColdFusion Builder will make you even more productive than using ColdFusion alone.

Service Oriented Architecture–a buzzword with substance

For the last few years across the software industry you may have noticed a move from delivering software within a single channel or platform to a multidimensional approach to software availability. A great example of this is Twitter, the microblogging site that gains an estimated 5 to10 thousand new subscribers every day. While Twitter was widely accepted and welcomed by the web community from its inception, Twitter did not grow to its present popularity as a browser-based site alone. By exposing services via an application programming interface (API), Twitter encouraged developers to build their own applications to allow social growth via other popular browser-based web applications, mashups, iPhone, Blackberry, and other mobile devices as well as desktop applications such as the wildly popular TweetDeck, built on Adobe AIR. This is all possible due to the infrastructure provided by service-oriented architecture (SOA). By exposing functionality as services Twitter was able to grow exponentially because developers can create engaging applications upon the core infrastructure using Flex, ColdFusion, .NET, Java, or any other language for any platform.
SOA provides the foundation for many great applications aside from Twitter. All have the same thing in common though: a well-documented API that is exposed via web services to be consumed by a variety of applications through predetermined protocols such as SOAP and REST. While building the next great viral application may not be on your agenda, if you are reading this I can assume that building reliable software quickly is vital to the success of your project. ColdFusion has always enabled rapid application development (RAD) for the service tier. ColdFusion 9 continues to build upon this ease of development by not only improving upon service creation, but also exposing key infrastructure as services to be consumed from a wide range of applications, including Adobe Flex applications. Extending this service tier in ColdFusion is a simple task, which then allows you to extend the same core functionality of your application to any platform regardless of language such as JavaScript, Ruby, PHP, or even non-web languages like Objective C for iPhone development.

A Brief History of SOA in ColdFusion

With ColdFusion, you can create your own services by writing ColdFusion Components (CFCs) and exposing them as web services. These services can be consumed in a multitude of ways from REST and SOAP to Flash Remoting and AMF. ColdFusion introduced CFCs in ColdFusion MX 6 in 2002 as a way to organize code and take advantage of the underlying J2EE platform architecture. Aside from allowing implementation of popular object-oriented design patterns and helping to promote code reuse and maintainability, the introduction of CFCs added remoting, which allowed developers to easily create exposed services by simply marking a ColdFusion function definition's access type as remote.
In 2009 Adobe furthered the push of interoperability across products (earlier in 2006 Adobe improved Creative Suite products by allowing designers to exchange files amongst the programs) by introducing a new product and rebranding an existing product. These products, now available as Adobe ColdFusion Builder (a ColdFusion IDE) and Adobe Flash Builder 4 (Flex/ActionScript IDE), automate many of the steps in developing, configuring, exposing, and consuming services.

Creating services with ColdFusion Builder

ColdFusion Builder is the first new ColdFusion IDE introduced specifically for developers since HomeSite+ was packaged with Dreamweaver MX 2004. ColdFusion Builder not only acts as a powerful ColdFusion IDE built on top of the Eclipse platform, it also takes over some of the features that were previously included in Adobe Flex Builder 3, namely CFC code generation and ActionScript file generation.
Creating ActionScript classes against a database table
Using ColdFusion Builder, a developer can quickly create services from a database for consumption in an application. Not only does ColdFusion Builder generate the necessary CFCs, but it can also generate the necessary AS3 files to be used in a Flex application. If you installed the samples when installing ColdFusion Builder, you will have a file named in the <cfbuilder_install>/samples directory. To install this extension, follow these steps:
  1. Choose Adobe ColdFusion Builder > Preferences from within ColdFusion Builder on Mac OS X (on Microsoft Windows, choose Window > Preferences) and select Extensions under ColdFusion in the treeview (see Figure 1).
Select Extensions under ColdFusion in the Preferences dialog box.
Figure 1. Select Extensions under ColdFusion in the Preferences dialog box.
  1. Click Install, browse to the <cfbuilder_install>/samples directory, and select As with all extensions you will install in ColdFusion Builder, you will be presented with a Wizard that will walk you through installing the extension (see Figure 2). Click Next.
The Extension Install wizard.
Figure 2. The Extension Install wizard.
  1. Select the ColdFusion server you will be connecting to (see Figure 3). If you want to set up a new server, click Add Server. The ColdFusion web root and the install location will be automatically populated from the server details. (You may change the install directory, but it must be located somewhere under the ColdFusion web root.)
Select your ColdFusion server and install details.
Figure 3. Select your ColdFusion server and install details.
  1. Click Next. Review the installation summary and then click Finish to complete the extension installation.
This extension can create AS3 files from database tables or from a CFC. For the first example, you'll generate an AS3 file directly from a database table in the cfartgallery database, which is installed with ColdFusion if you chose to do so during installation. To do this you need to connect to a development ColdFusion server with RDS enabled.
Note: Do not enable RDS in a non-development environment as it is a security risk that could allow a malicious user access to files and databases.
  1. Locate the RDS Dataview view. In the default view of ColdFusion Builder, RDS Dataview is located in the upper rightmost pane in the default perspective. If you have closed the RDS Dataview view, choose Window > Show View > RDS Dataview in ColdFusion Builder to open it.
    Note: If you are new to Eclipse, you can learn about perspectives, workspaces, and more at the Eclipse site.
    RDS Dataview is a treeview that lists all currently configured servers available to you within ColdFusion Builder. (You can configure a new server using the Servers view in ColdFusion Builder.)
  2. Expand the tree for your development ColdFusion instance and locate the cfartgallery database. Expand the cfartgallery database and expand the Tables folder under it (see Figure 4).
The tables of cfartgallery shown in RDS Dataview.
Figure 4. The tables of cfartgallery shown in RDS Dataview.
  1. Since you installed the AS3 Class Generator extension, right-clicking on any table will present you with the option to generate an ActionScript 3.0 class from the table. Right-click APP.ART and select Generate AS Class From DB Table (see Figure 5).
Generating an ActionScript class from a database table.
Figure 5. Generating an ActionScript class from a database table.
  1. Specify where you would like ColdFusion Builder to create the ActionScript class files (see Figure 6). Optionally, you may select Include AS Metadata Tags. For more information on each metadata tag, see Using Adobe ColdFusion Builder. You may also specify the package name at this time. If you do not, the package name will be left blank upon class generation.
  2. Click OK.
Specify a location for the ActionScript Class Generator.
Figure 6. Specify a location for the ActionScript Class Generator.
You may now begin editing and using the file (see Figure 7) within your Flex project.
The generated ActionScript class.
Figure 7. The generated ActionScript class.
Generating Object Relational Mapping CFCs in ColdFusion Builder
As I do for most of my projects, you may wish to use ColdFusion as a service tier for handling data persistence across multiple deployments. Whether your application is written in HTML and JavaScript, Flex, ActionScript, Java, or even Objective C for iPhone apps, ColdFusion Builder can easily generate Object Relational Mapping (ORM) persistence services against ColdFusion 9, which implements Hibernate for ORM.
Note: You can still create ORM service layers in previous versions of ColdFusion, and you can still use ColdFusion Builder to generate ActionScript files from these CFCs even if you do not have ColdFusion 9.
Follow these steps to generate CFCs for a specific database table automatically in ColdFusion Builder:
  1. Install the ORM Code Generator extension just as you did in the previous example. The file, ORM Code, is located in <cfbuilder_install>/samples. Once installed, you will have a new menu option available in RDS Dataview when you right-click on a table name (see Figure 8).>
Generating the ORM CFC.
Figure 8. Generating the ORM CFC.
  1. Choose ORM Code Generator > Generate ORM CFC from the table's context menu.
  2. In the ORM Code Generator dialog box, select the location to store the generated files. For this example select the option to generate an Application.cfc file that contains the ORM settings as well as the option to create a view based on the database table you selected (see Figure 9).
  3. Click OK.
Generating an ORM CFC.
Figure 9. Generating an ORM CFC.
Three files are generated by the process.
The first file, Application.cfc, contains two important directives. The first directive lets the ColdFusion server know you are going to be enabling ORM support for the current application. The second is used by the generated CFC to specify what data source the CFC should use. Keeping this information in the Application.cfc file allows you to easily edit this data source name in just one place if the data source changes, for example as you move from a development to a production environment.
The second file generated by this process is named ART_view.cfm, and loads the set of data within the table and displays it in table form (See the ColdFusion 9 documentation for an explanation of the generated code as well as more ORM functions.) You can run this file in a browser, and amazingly, without writing any CFML you now are presented with an HTML table (see Figure 10) with all of your database table records ready to be styled with CSS!
The table produced by ART_view.cfm.
Figure 10. The table produced by ART_view.cfm.
The third file generated is a CFC named ART.cfc. This CFC is set up with all of the necessary properties to be consumed by the ORM functions in ColdFusion. This basic CFC and the associated ORM functionality provided by ColdFusion 9 may now be wrapped in your service tier and exposed as a web service for use in a variety of applications.
Because you have the ActionScript Class Generator installed from the previous example, you can right-click the CFC to generate the associated ActionScript class for use in your Flex projects.
Generating an ActionScript class from a CFC.
Figure 11. Generating an ActionScript class from a CFC.
There are two new options that are not available when you generate the class directly from a database table (see Figure 11). The first is Include CF-AIR Offline Metadata, which includes the directives for persisting data offline in the Adobe AIR SQLite database. The second is a data source, which is only required if the CFC does not contain this information. The generated file may now be used within your Flex applications to handle data persistence reliably and efficiently, thanks to ColdFusion 9—and with ColdFusion Builder, you didn't have to write a line of code!

ColdFusion as a Service

In practice, ColdFusion features are often used on the back end of applications with an alternative technology on the front end. These server-side functions, such as sending mail and creating PDFs are typically wrapped up in CFCs and exposed as services to distributed applications. With ColdFusion 9 , Adobe has exposed many of these server-side functions as native services, enabling developers who don't know CFScript or CFML to expedite the development and deployment of web applications.
A classic example for the need of a server-side technology within a web application is for sending mail. Almost every web developer I have met has created a contact form, and every one has had to decide on a server-side technology to parse and send the contents of the form via email. ColdFusion 9 allows the client side developer to make a call to a ColdFusion service to send the contents of the form, all without writing a single line of ColdFusion code.
As I mentioned in the introduction, any good SOA implementation needs to be well-documented. ColdFusion is no exception. CFCDocExplorer allows developers to view the CFCs that make up the ColdFusion as a Service (CFaaS) web services in classic JavaDoc style. For this example, refer to the documentation for mail.cfc by navigating to http://localhost:8500/CFIDE/services/mail.cfc (this is the default path for the single server installation of ColdFusion 9, your path may be different). You may be asked to log in with your ColdFusion Administrator or RDS password.
A CFaaS Example–Sending email directly from JavaScript
Sending mail from client-side JavaScript with ColdFusion as a Service is a simple task. Two files make up the call in this example. The first is an HTML page that collects data via a HTML form.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ""> <html xmlns=""> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>ColdFusion 9 CFaaS Sample</title> <script type="text/javascript" src="lib/js/yui/utilities.js"></script> <script type="text/javascript" src="lib/js/mail.js"></script> <style type="text/css"> form div { width: 600px; float: left; clear: both; padding: 5px; } input, textarea { float: left; clear: none; } textarea { width: 300px; height: 125px; } label { width: 200px; float: left; clear: none; text-align: right; padding-right: 5px; font-weight: bolder; } form div button { margin: 0 0 0 205px; } </style> </head> <body> <form id="frmMail" action="javascript:void(0);"> <div><label for="mailserver">Mail Server:</label><input type="text" id="mailserver" /></div> <div><label for="serviceuser">CFaaS Service User:</label><input type="text" id="serviceuser" /></div> <div><label for="servicepassword">CFaaS Service Password:</label><input type="password" id="servicepassword" /></div> <div><label for="mailto">To:</label><input type="text" id="mailto" /></div> <div><label for="mailfrom">From:</label><input type="text" id="mailfrom" /></div> <div><label for="mailsubject">Subject:</label><input type="text" id="mailsubject" /></div> <div><label for="mailcontent">Content:</label><textarea id="mailcontent">This is a test message I am sending from JavaScript through CFaaS!</textarea></div> <div><button onclick="mail.send();">Send Mail</button></div> </form> </body> </html>
Notice that when the user clicks Send Mail, a JavaScript object takes control of the process (imported as mail.js, although JavaScript functions directly in the HTML would work also). The JavaScript object contains a send() method that accepts the form parameters that will be included in the service call.
mail = { /** * @description Sends mail via CFaaS * @method send * @public * @return {void} */ send: function () { // create a callback object var callback = { success: mail.successSend, failure: mail.failureSend } // set up the params to pass the service var postData = "method=send&&username=&password=&bcc=&cc=&type=&failto=&mailerid=&priority=&timeout=&usessl=&usetls=&wraptext=&replyto=&mimeattach=&charset=" + "&server=" + escape(YAHOO.util.Dom.get('mailserver').value) + "&serviceusername=" + escape(YAHOO.util.Dom.get('serviceuser').value) + "&servicepassword=" + escape(YAHOO.util.Dom.get('servicepassword').value) + "&from=" + escape(YAHOO.util.Dom.get('mailfrom').value) + "&to=" + escape(YAHOO.util.Dom.get('mailto').value) + "&subject=" + escape(YAHOO.util.Dom.get('mailsubject').value) + "&content=" + escape(YAHOO.util.Dom.get('mailcontent').innerHTML); // make the Ajax call YAHOO.util.Connect.asyncRequest('POST', '../../CFIDE/services/mail.cfc', '', postData); }, successSend: function (o) { alert('Your mail has been sent via ColdFusion 9 CFaaS!'); }, failureSend: function (o) { alert('An error occurred while sending mail.'); } }
For added simplicity, this JavaScript call uses the Yahoo! User Interface Library (YUI) to make the Ajax POST to CFaaS. Any other JavaScript library that supports Ajax would work as well. The URL that the asynchronous request is sent to is the path of the CFC that ColdFusion uses to define the Mail service. Referring to the CFCDocExplorer documentation for the mail service, mail.cfc exposes one method that accepts a plethora of arguments. Once the user enters the necessary data into the HTML form and clicks ‘Send Mail', the JavaScript object's send() method is invoked. This posts all necessary arguments to CFaaS, including two security arguments that are used to authenticate the current asynchronous call. These credentials are defined in the ColdFusion Administrator under Security > User Manager. Create a new user and define a password for the service user.
Defining the user's credentials in the ColdFusion Administrator.
Figure 12. Defining the user's credentials in the ColdFusion Administrator.
You will then need to define which services the user is able to access. For this example, you will need to select the ‘Mail Service'. After you have selected the appropriate services, click ‘Add User'.
Assigning exposed services in the ColdFusion Administrator.
Figure 13. Assigning exposed services in the ColdFusion Administrator.
You must also add permitted IP addresses under Security > Allowed IP Addresses (NOTE: if no addresses are entered, no users may invoke exposed services, unlike the behavior in debugging IP address settings). Please keep in mind that the example above is not necessarily secure. Make sure when implementing applications that utilize CFaaS exposed services, you define your individual use case and include steps to include necessary security.
To test the example, navigate to mailtest.html within the CF web root where you extracted the sample files. Enter the requested information and click the ‘Send Mail' button. If you do not receive a success alert, you may need to check the CF logs to ensure you have your mail server configured properly in the ColdFusion Administrator.

Where to go from here

Check out the Services Browser in ColdFusion Builder to learn more about exposed services in ColdFusion 9 such as:
  • Mail
  • PDF
  • FTP
  • Database queries and stored procedures
For Adobe Flex developers, take a minute to explore the ActionScript 3.0 classes available for consuming most of the ColdFusion services listed above quickly and easily. More information may be found in Developing ColdFusion 9 Applications: Flex and AIR Integration in ColdFusion.
Whether you are creating killer social applications or developing an intranet application for your company, ColdFusion 9 and ColdFusion Builder make developing a service tier easier than ever, regardless of your delivery method, device, or ColdFusion expertise. As a RAD platform, ColdFusion, Flex, and their associated IDEs once again set themselves apart as the go-to products for web and desktop application development. This article barely scratches the surface of what's new in ColdFusion Builder and ColdFusion 9. I strongly recommend that you take the time to visit Adobe Developer Connection, the ColdFusion Cookbook, and Flex Cookbook to learn more about Adobe ColdFusion and the power of SOA.