Implementing ColdFusion services

This example shows how to implement a basic service in ColdFusion. The example is based on code that Flash Builder generates when accessing a database table. See Generating a sample ColdFusion service from a database table.

This example implements client-side typing. See Client-side and server-side typing.

For examples of server-side typing, see Flash Builder server-side type examples.

<cfcomponent output="false"> 
 
<!--- 
    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="getAllemployees" 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 qAllItems=""> 
        <cfquery name="qAllItems" datasource="employees"> 
            SELECT * FROM employees 
        </cfquery> 
        <cfreturn qAllItems> 
         
    </cffunction> 
 
    <cffunction name="getemployees" output="false" access="remote"  returntype="any" > 
        <cfargument name="emp_no" type = "numeric" required="true" /> 
 
        <!--- Retrieve a single record and return it as a query or array. 
                Add authorization or any logical checks for secure access to your data ---> 
         
        <cfset var qItem=""> 
        <cfquery name="qItem" datasource="employees"> 
            SELECT * 
            FROM employees 
            WHERE emp_no = <CFQUERYPARAM CFSQLTYPE="CF_SQL_INTEGER" VALUE="#ARGUMENTS.emp_no#"> 
        </cfquery> 
 
        <cfreturn qItem> 
         
    </cffunction> 
 
</cfcomponent>

Highlights of EmployeeService:

• Connects to the employees database and accesses the employees table in the database.

• Returns an array of objects.

  When programming using the Flex framework, services return data only. The client application handles the formatting and presentation of the data. This model differs from traditional ColdFusion CFM applications that return data formatted in an HTML template.

  Flex handles returned recordsets as an array of objects. Each row represents a retrieved record from the database. Each column of the database record becomes a property of the returned object. The client application can now access the returned data as objects with a set of properties.

  Configure the data type for the returned object. See Client-side and server-side typing.

• The ColdFusion server provides error handling.

  The error handling provided by ColdFusion is useful when debugging a service. In the ColdFusion Administrator, modify the Debugging and Logging settings to provide robust debugging information.

  The Flash Builder Test Operation interface displays information returned by ColdFusion server.

  See Debugging remote services for more information on testing services.

• Uses cfqueryparam for constructing database queries.

  cfqueryparam is a defense against SQL injection statements in calls to the server. For more information, see Enhancing security with cfqueryparam in the ColdFusion documentation.

• Authenticate users before providing access to the functions in this service.

  The sample code does not illustrate how to authenticate users. See the ColdFusion documentation, About User Security.

Flash Builder tools allow you to implement paging of data retrieved from a remote service. Paging is the incremental retrieval of large data sets.

Flash Builder requires specific function signatures to implement paging. The following code example provides an example of one way to implement a ColdFusion service for paged data.

The EmployeeServicePaged example is based on the code generated by Flash Builder when accessing a database table. See Generating a sample ColdFusion service from a database table.

<cfcomponent output="false"> 
 
<!--- 
    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="count" output="false" access="remote" returntype="numeric" > 
 
        <!---        Return the number of items in your table. 
                Add authorization or any logical checks for secure access to your data ---> 
        <cfquery name="qread" datasource="employees"> 
            SELECT COUNT(emp_no) AS itemCount FROM employees 
        </cfquery> 
        
        <cfreturn qread.itemCount> 
         
    </cffunction> 
     
    <cffunction name="getemployees_paged" output="false" access="remote" returntype="any" > 
        <cfargument name="startIndex" type="numeric" required="true" /> 
        <cfargument name="numItems" type="numeric" required="true" /> 
 
    <!---    Return a page of numRows number of records as an array or 
        query from the database for this startRow. 
        Add authorization or any logical checks for secure access to your data ---> 
    <!---    The LIMIT keyword is valid for mysql database only. 
        Modify it for your database ---> 
         
        <cfset var qRead=""> 
        <cfquery name="qRead" datasource="employees"> 
            SELECT * FROM employees LIMIT #startIndex#, #numItems# 
        </cfquery> 
        <cfreturn qRead> 
         
    </cffunction> 
</cfcomponent>

The EmployeeServicePaged service returns untyped data. Use the Flash Builder tools to configure the return type for getEmployees_Paged(). After configuring the return type, enable paging on the getEmployees_Paged() operation.

Flash Builder tools allow you to implement data management functionality for remote services. Data management is the synchronization of updates to data on a server from the client application.

Flash Builder requires a combination of specific function signatures to implement data management. The following code example provides an example of one way to implement a ColdFusion service for data management.

The following EmployeeServiceDM example is based on the code generated by Flash Builder when accessing a database table. See Generating a sample ColdFusion service from a database table.

<cfcomponent output="false"> 
 
<!--- 
    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="getAllemployees" output="false" access="remote" returntype="any" > 
 
        <!--- Auto-generated method 
                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 qAllItems=""> 
        <cfquery name="qAllItems" datasource="employees"> 
            SELECT * FROM employees 
        </cfquery> 
        <cfreturn qAllItems> 
         
    </cffunction> 
 
    <cffunction name="getemployees" output="false" access="remote"  returntype="any" > 
        <cfargument name="emp_no" type = "numeric" required="true" /> 
 
        <!---   
                Retrieve a single record and return it as a query or array. 
                Add authorization or any logical checks for secure access to your data ---> 
         
        <cfset var qItem=""> 
        <cfquery name="qItem" datasource="employees"> 
            SELECT * 
            FROM employees 
            WHERE emp_no = <CFQUERYPARAM CFSQLTYPE="CF_SQL_INTEGER" VALUE="#ARGUMENTS.emp_no#"> 
        </cfquery> 
 
        <cfreturn qItem> 
         
    </cffunction> 
 
    <cffunction name="createemployees" output="false" access="remote" returntype="any" > 
        <cfargument name="item" required="true" /> 
 
        <!---   Insert a new record in the database. 
            Add authorization or any logical checks for secure access to your data ---> 
 
        <cfquery name="createItem" datasource="employees" result="result"> 
            INSERT INTO employees (birth_date, first_name, last_name, gender, hire_date) 
                    VALUES (<CFQUERYPARAM cfsqltype="CF_SQL_DATE" VALUE="#item.birth_date#">, 
                            <CFQUERYPARAM cfsqltype="CF_SQL_VARCHAR" VALUE="#item.first_name#">, 
                            <CFQUERYPARAM cfsqltype="CF_SQL_VARCHAR" VALUE="#item.last_name#">, 
                            <CFQUERYPARAM cfsqltype="CF_SQL_CHAR" VALUE="#item.gender#">, 
                            <CFQUERYPARAM cfsqltype="CF_SQL_DATE" VALUE="#item.hire_date#">) 
 
        </cfquery> 
         
        <!--- The GENERATED_KEY is valid for mysql database only, you can modify it for your database ---> 
        <cfreturn result.GENERATED_KEY/> 
         
    </cffunction> 
 
    <cffunction name="updateemployees" output="false" access="remote" returntype="void" > 
        <cfargument name="item" required="true" /> 
 
        <!--- Update an existing record in the database. 
              Add authorization or any logical checks for secure access to your data ---> 
 
         <cfquery name="updateItem" datasource="employees"> 
            UPDATE employees SET birth_date = <CFQUERYPARAM cfsqltype=CF_SQL_DATE VALUE="#item.birth_date#">, 
                             first_name = <CFQUERYPARAM cfsqltype=CF_SQL_VARCHAR VALUE="#item.first_name#">, 
                             last_name = <CFQUERYPARAM cfsqltype=CF_SQL_VARCHAR VALUE="#item.last_name#">, 
                             gender = <CFQUERYPARAM cfsqltype=CF_SQL_CHAR VALUE="#item.gender#">, 
                             hire_date = <CFQUERYPARAM cfsqltype=CF_SQL_DATE VALUE="#item.hire_date#"> 
 
            WHERE emp_no = <CFQUERYPARAM CFSQLTYPE="CF_SQL_INTEGER" VALUE="#item.emp_no#"> 
        </cfquery> 
                 
    </cffunction> 
 
    <cffunction name="deleteemployees" output="false" access="remote" returntype="void" > 
        <cfargument name="emp_no" type="numeric" required="true" /> 
 
        <!--- Delete a record in the database. 
              Add authorization or any logical checks for secure access to your data ---> 
 
        <cfquery name="delete" datasource="employees"> 
            DELETE FROM employees 
            WHERE emp_no = <CFQUERYPARAM CFSQLTYPE="CF_SQL_INTEGER" VALUE="#ARGUMENTS.emp_no#"> 
        </cfquery> 
              
    </cffunction> 
</cfcomponent>

The EmployeeServiceDM service returns untyped data. Use the Flash Builder tools to configure the return type for getAllEmployeess() and getEmployees(). Use Employee for the custom data type returned by these operations.

After configuring the return type, enable data management on the Employee data type.