Creating ColdFusion services for client applications

Create a CFC that accesses a database
(Optional) Test the service
Import the service into Flex and bind returned data to application components

When you access a remote service, you typically retrieve records from a database and display them in the client application. This tutorial shows how to access a remote database and display retrieved records in a DataGrid.

View full size graphic

The tutorial illustrates the following concepts:

Using a ColdFusion component (CFC) to implement service operations that query a database.
Binding a CFC service operation to a Flex data control, such as a DataGrid.
Sampling the data returned from a service operation to configure a data type for the returned data.
Running the application and viewing the returned data in the DataGrid.

Create a CFC that accesses a database

This tutorial accesses the cfbookclub database that is provided with a ColdFusion installation. It lists the contents of the Books table in the database. However, you can modify this tutorial to select records from any database you have access to.

This tutorial assumes that you have a local installation of ColdFusion 8 or ColdFusion 9 and the ColdFusion server is running.

In your web root, create a folder named books.

In your favorite ColdFusion editor, create the following CFC. Name it BookService.cfc and place it in the books folder in your web root.

BookService.cfc selects all the records from the Books table in the cfbookclub database.

<!--- 
This sample service contains functions that illustrate typical service operations. 
This code is for prototyping only. 
Authenticate the user prior to allowing them to call these methods. You can find more 
information at http://www.adobe.com/go/cf9_usersecurity 
---> 
<cffunction name="getBooks" output="false" access="remote" returntype="any" > 
    <!--- Retrieve set of records and return them as a query or array. ---> 
    <!--- Add authorization or any logical checks for secure access to your data ---> 
    <cfset var qAllBooks=""> 
    <cfquery name="qAllBooks" datasource="cfbookclub"> 
        SELECT * FROM Books 
    </cfquery> 
    <cfreturn qAllBooks> 
</cffunction>

In BookService.cfc, examine the code that calls the database:

Flex expects data returned by the operation to be an object or an array of objects. Each object in the array corresponds to a retrieved record from the database, containing values for each column in the record.

The cfquery, qAllBooks, accesses the Books table in the cfbookclub database. ColdFusion returns an array of records from the database.

(Optional) Test the service

It is always a good idea to test a service before you access it from an application.

Create bookservicetest.cfm to test the CFC. This script uses cfdump to view the results of the service operation.

Testing getBooks()... 
<cfinvoke component="BookService" method="getBooks" returnvariable="books"/> 
<p> <cfdump var="#books#"/>

Save bookservicetest.cfm in the books folder next to BookService.cfc.
From a web browser, run the script to test the service:
```
http://localhost:8500/books/bookservicetest.cfm
```

View full size graphic

You can also test a service after importing the service into Flash Builder. Use Test Operation, which is available from the Data/Service view.

Import the service into Flex and bind returned data to application components

The relationship between client code and server code in Flex differs from the traditional relationship in a server template.

In a traditional relationship, a server template mixes server code with client code. When the client queries a database, it dynamically embeds HTML code with returned data.

Flex, however, separates client code from server code. The remote service returns only data. Flex binds the returned data to user interface components in the client application.

In Flash Builder, select New > Flex Project to create a ColdFusion server project. Name the project Books.

Set the Application Server Type to ColdFusion. Enable Use Remote Object Access Service and select ColdFusion Flash Remoting.

View full size graphic
Click Next. Validate your configuration.
Set the output folder to the books folder containing the service. Click Finish.

Flash builder creates Books.mxml and opens the file in the MXML editor.

Select Design to open the editor in Design mode.
In Design mode, drag a DataGrid control to the design area.

The DataGrid control is available under Controls in the Components view.
From the context menu for the DataGrid, select Bind to Data.
In the No Services Defined dialog, click Yes to connect to a service.
In the Connect to Data/Service wizard, select ColdFusion. Click Next.

Flash Builder provides multiple ways to connect to a data service. In this scenario, you first create the user interface. Then from a user interface component, you connect to a service and specify the remote operation.
Click Browse and navigate to the BookService.cfc you created previously. Click Finish.

Provide authorization credentials as needed for your system.

The Data Services View now displays the BookService.
Again, from the context menu for the DataGrid, select Bind to Data.

The Bind to Data dialog now opens with New Service Call selected.

BookService is the only service available in the Flex project.

getBooks() is the only operation available in the service.
In the Bind to Data dialog, select Configure Return Type to define the data type for returned data.

Flex uses the return data type to access service operations. The BookService service does not define the data type for returned data. Flash Builder uses client-side typing to define a custom data type for the returned data.

Some services, such as those provided by LiveCycle Data Services, provide server-side typing. With server-side typing, Flash Builder does not have to configure the data type for returned data.
In the Configure Return Type dialog, Auto-Detect the Return Type is selected by default. Click Next.

Flash Builder introspects the service to determine the data and data types returned.
Specify Book in the Array Of field to define a custom type for returned data.

The BookService returns an array of records from the data service. Each record is a complex data type representing a database record for a book. The custom type Book provides access to each field of the record.

The Configure Return Type dialog displays the properties of the data type returned by the service. Click Finish.

When Flash Builder configures a return type, it accesses the database to create a value object. The properties of the custom data type are derived from the value object. You can view the properties of the data type before proceeding.
In the Bind to Data dialog, click OK.

Flash Builder binds the data returned from the service call to the DataGrid component. It modifies the columns of the DataGrid, binding the value returned for each Book property to a column in the DataGrid.

View full size graphic
Make sure the DataGrid is still selected. In the Properties view, click Configure Columns and then do the following steps:
1. Select the ISSPOTLIGHT column. Click Delete to delete the column.
2. Delete all columns except TITLE and GENRE.
3. Select the TITLE column. Edit the Header Text field to rename the column Title.
4. Rename the GENRE column to Genre.
5. With the GENRE column selected, click Up to rearrange the order of the columns.
6. Click OK.
  
  View full size graphic
In Design View, grab the far left handle of the DataGrid and resize it to a more normal shape. Save and run the application.

View full size graphic