When you create a new Flex project, you can add project properties that allow you to easily test your Flex application with the ColdFusion server. Follow these steps to create a new Flex project:

You should see that the application is retrieved from the folder on the ColdFusion server using the server's root URL and the subfolder in which the output files are generated.

Just as with the Remoting Service on LiveCycle Data Services or BlazeDS, to use Flash Remoting from a Flex application, it must be configured on the server. When you install ColdFusion, a folder named WEB-INF/flex is created that contains a default set of configuration files.

Flash Remoting access is configured in one of two files in the WEB-INF/flex folder:

ColdFusion includes a predefined Flash Remoting destination definition with an id of ColdFusion in either services-config.xml or remoting-config.xml that looks like this:

<destination id="ColdFusion">
  <channels>
    <channel ref="my-cfamf"/>
  </channels>
  <properties>
    <source>*</source>
    <!-- define the resolution rules and access level of
      the cfc being invoked -->
    <access>
      <!-- Use the ColdFusion mappings to find CFCs, by default

only CFC files under your webroot can be found. -->
      <use-mappings>false</use-mappings>
      <!-- allow "public and remote" or just "remote" methods
        be invoked -->
      <method-access-level>remote</method-access-level>
    </access>
    <property-case>
      <!-- cfc property names -->
      <force-cfc-lowercase>false</force-cfc-lowercase>
      <!-- Query column names -->
      <force-query-lowercase>false</force-query-lowercase>
      <!-- struct keys -->
      <force-struct-lowercase>false</force-struct-lowercase>
    </property-case>
  </properties>
</destination>

These key destination properties are worth a detailed description:

The default ColdFusion destination is designed to be usable with its initial property settings. In most cases, you can start calling CFC functions from a Flex client application without changing any of the server-side configuration options.

The CFC is known to the Flex client application by its fully qualified name and location, declared with dot notation. This String value is passed to the RemoteObject component's source property to determine which component will be called on the server.

ColdFusion uses a naming pattern whereby CFCs are known by the name of the file in which the component is defined (without the file extension), prefixed with the names of the folders in which it's stored, starting at the Web root folder. Folder and component names are separated with dot characters, just like packages in Java. So, for example, a CFC that's defined in a file named MyComponent.cfc and stored in a subfolder under the ColdFusion Web root named flex3bible/cfc would be referred to from Flex as:

flex3bible.cfc.MyComponent

If you're working on a development server that has RDS, you can generate a CFC's documentation by navigating to the component from a Web browser. The documentation includes the exact string you need to set the component's source accurately in Flex. For example, you can browse to the HelloService.cfc file stored in the Web root folder's flex3bible/chapter26 folder with this URL:

http://localhost:8500/flex3bible/chapter26/HelloService.cfc

Figure 26.3 shows the resulting CFC documentation. The string value you use as the source attribute in Flex is displayed twice: once at the top of the documentation page and again in the hierarchy section.

You can create an instance of the RemoteObject component that works with the ColdFusion destination in either MXML or ActionScript. In addition to the object's unique id, you set object's destination to the id of the destination on the server, named by default ColdFusion. The object's source attribute is set to the fully qualified name and location of the CFC, as described in the preceding section.

The code to create a RemoteObject and set its required properties in MXML looks like this:

<mx:RemoteObject id="helloService"
  destination="ColdFusion"
  source="flex3bible.chapter26.HelloService"/>

Figure 26.3. Automatically generated CFC documentation, including the component's fully qualified name and location

The code to create the same object in ActionScript looks like this:

import mx.rpc.remoting.RemoteObject;
var helloService:RemoteObject = new RemoteObject("ColdFusion");
helloService.source = "flex3bible.chapter26.HelloService";

After you've declared the RemoteObject and set its source and destination properties, you're ready to make runtime calls to remote CFC functions.

You call CFC functions as though they were local methods of the RemoteObject. For example, the CFC in Listing 26.1 has a public method named helloWorld() that returns a simple String. As with local functions, you can call the remote method upon any application event. For example, this code calls the server-side helloWorld() method upon a Button component's click event:

<mx:Button label="Click to say hello"
  click="helloService.helloWorld()"/>

You also can call a CFC function by calling the RemoteObject component's getOperation() method to create an instance of the Operation class. The following code creates the Operation object and then calls its send() method to call the remote method:

import mx.rpc.remoting.mxml.Operation;
private function callIt():void
{
  var op:Operation = helloService.getOperation("helloWorld")
    as Operation;
  op.send();
}

This technique allows you to determine which remote method will be called at runtime, instead of having to hard code the method name.

A binding expression used to pass returned data to application components consists of three parts, separated with dots:

At runtime, the method is created as an Operation object that's a member of the RemoteObject instance. The Operation object's lastResult property is populated with data when it's received from the server.

The lastResult property is explicitly typed as an ActionScript Object, but at runtime its native type is determined by the type of data that's returned from the server. A String returned from ColdFusion is translated into an ActionScript String value, so a binding expression that handles the value returned from the simple helloWorld() method can be used to pass the returned value to a Label or other text display control.

The application in Listing 26.2 calls the remote helloWorld() CFC function and displays its returned data in a Label control with a binding expression in its text property.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
  backgroundColor="#EEEEEE">

  <mx:RemoteObject id="helloService"
    destination="ColdFusion"
    source="flex3bible.chapter26.HelloService"/>

  <mx:Button label="Hello World" click="helloService.helloWorld()"/>

  <mx:Label text="{helloService.helloWorld.lastResult}"
    fontSize="12"/>

</mx:Application>

As with other RPC components, you can handle results of a call to a CFC function with the RemoteObject component's result event. This event dispatches an event object typed as mx.rpc.events.ResultEvent, the same event object that's used by the other RPC components HTTPService and RemoteObject. The event object's result property references the returned data.

To handle and save data using the result event, follow these steps:

You can listen for the result event with either an MXML attribute-based event listener or a call to the ActionScript addEventListener() method. The attribute-based event listener looks like this:

<mx:RemoteObject id="myService" destination="helloClass"
  source="flex3bible.chapter26.ContactService"
  result="resultHandler(event)"/>

When using addEventListener() to create an event listener, you can designate the event name with the String value result, or with the ResultEvent class's RESULT static constant:

var contactService:RemoteObject = new RemoteObject("ColdFusion");
contactService.source =
   source="flex3bible.chapter26.ContactService";
contactService.addEventListener(ResultEvent.RESULT,
   resultHandler);
contactService.getAllContacts();

Listing 26.3 uses a result event handler function to capture and present data that's been returned from a CFC function.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
  backgroundColor="#EEEEEE" creationComplete="initApp()"
  xmlns:view="view.*">
  <mx:Script>
    <![CDATA[
      import mx.collections.ArrayCollection;
      import mx.rpc.events.ResultEvent;
      import mx.rpc.remoting.RemoteObject;
      [Bindable]
      private var contactData:ArrayCollection;
      private var contactService:RemoteObject;
      private function initApp():void
      {

contactService = new RemoteObject("ColdFusion");
        contactService.source = "flex3bible.chapter26.ContactService";
        contactService.addEventListener(ResultEvent.RESULT,
   resultHandler);
      }
      private function resultHandler(event:ResultEvent):void
      {
       contactData = event.result as ArrayCollection;
      }
    ]]>
  </mx:Script>
  <mx:Button label="Hello World"
   click="contactService.getAllContacts()"/>
  <view:ContactsGrid dataProvider="{contactData}"/>
</mx:Application>

Listing 26.4 shows the code for the CFC that's called by this and other applications in this section. Notice that the Query object is created manually in ColdFusion code, rather than being generated with a <cfquery> command. As a result, the case of the column names is controlled by this call to the ColdFusion QueryNew() function, rather than being derived from a database query's metadata:

<cfset var
   qContacts=queryNew('contactId,firstname,lastname,city')>

<cfcomponent name="ContactService"
  hint="Delivers Contact data from an XML file to a Flex application">
  <cfapplication name="flex3BibleChapter26" sessionManagement="true">
  <!--- Initialize data set in memory if it doesn't already exist --->
  <cfif not structKeyExists(session, "qContacts")>
    <cfset createDataSet()>
  </cfif>

  <!--- Returns all data from a query object --->
  <cffunction name="getAllContacts" returntype="query" access="remote">
    <cfreturn session.qContacts>
  </cffunction>
  <!--- Returns filtered data using query of query --->

<cffunction name="getFilteredContacts" returnType="query"
 access="remote">
  <cfargument name="firstname" type="string" required="true">
  <cfargument name="lastname" type="string" required="true">
  <cfset var qFiltered="">
  <cfquery dbtype="query" name="qFiltered">
    SELECT * FROM session.qContacts
    WHERE 0=0
  <cfif len(trim(firstname))>
    AND firstname LIKE '%#trim(arguments.firstname)#%'
  </cfif>
  <cfif len(trim(lastname))>
    AND lastname LIKE '%#trim(arguments.lastname)#%'
  </cfif>
 </cfquery>
 <cfreturn qFiltered>
</cffunction>
<!--- Returns the total count of Contacts --->
<cffunction name="getContactCount" returntype="numeric"
 access="remote">
  <cfreturn session.qContacts.recordCount>
</cffunction>
<!--- Called to create a query object from an XML file --->
<cffunction name="createDataSet" returntype="void" access="private">
  <cfset var strContacts="">
  <cfset var xContacts="">
  <cfset var i="">
  <cfset var qContacts=queryNew('contactId,firstname,lastname,city')>
  <cffile action="read" file="#expandPath('data/contacts.xml')#"
    variable="strContacts">
  <cfset xContacts=xmlParse(strContacts)>
  <cfloop from="1" to="#arrayLen(xContacts.contacts.row)#" index="i">
    <cfset QueryAddRow(qContacts)>
    <cfset qContacts.firstname[i]=xContacts.contacts.row[i]
      .firstname.xmltext>
    <cfset qContacts.lastname[i]=xContacts.contacts.row[i].</p>
      lastname.xmltext>
    <cfset qContacts.contactId[i]=xContacts.contacts.row[i].</p>
      contactId.xmltext>
    <cfset qContacts.city[i]=xContacts.contacts.row[i].city.xmltext>
  </cfloop>
  <cfset session.qContacts=qContacts>
 </cffunction>
</cfcomponent>

When you need to call more than one function from a CFC, you have to distinguish which event handler function should be called for each of them. You do this in MXML with the <mx:method > compiler tag, which is nested within a <mx:RemoteObject> tag set. Each <mx:method > tag represents a CFC function and can declare its own distinct result and fault event handlers.

The CFC in Listing 26.4, for example, has a function named getContactCount() that returns a numeric value and a function named getAllContacts() that returns a Query object (translated to an ArrayCollection in the Flex application). To handle each function's result event with its own distinct event handler function, you create the functions and then declare the <mx:method> tags as follows:

<mx:RemoteObject id="contactService"
  destination="ColdFusion"
  source="flex3bible.chapter26.ContactService">
  <mx:method name="getContactCount"
   result="countHandler(event)"/>
  <mx:method name="getAllContacts" result="dataHandler(event)"/>
</mx:RemoteObject>

The application in Listing 26.5 calls getContactCount() upon application startup to inform the user how many data items are available on the server. The call to getAllContacts() to actually retrieve the data is made only when the user clicks Get Contact Data.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:view="view.*" backgroundColor="#EEEEEE"
  creationComplete="contactService.getContactCount()">
  <mx:Script>
    <![CDATA[
      import mx.collections.ArrayCollection;
      import mx.rpc.events.ResultEvent;
      [Bindable]
      private var recordCount:Number;
      [Bindable]
      private var contactData:ArrayCollection;
      private function countHandler(event:ResultEvent):void
      {
        recordCount = event.result as Number;
      }
      private function dataHandler(event:ResultEvent):void
      {
        contactData = event.result as ArrayCollection;

}
    ]]>
  </mx:Script>
  <mx:RemoteObject id="contactService"
    destination="ColdFusion"
    source="flex3bible.chapter26.ContactService">
    <mx:method name="getContactCount" result="countHandler(event)"/>
    <mx:method name="getAllContacts" result="dataHandler(event)"/>
  </mx:RemoteObject>
  <mx:Label
    text="There are {recordCount} Contacts available on the server"/>
  <mx:Button label="Get Contact Data"
    click="contactService.getAllContacts()"/>
  <view:ContactsGrid dataProvider="{contactData}"/>
</mx:Application>

Figure 26.4 shows the resulting application. The Label at the top of the application displays the getContactCount() results immediately upon application startup, while the actual data is displayed only when the user requests it from the server.

Figure 26.4. An application using two different functions of a single CFC

Explicit arguments are passed in the same order in which they're declared in the CFC function. The CFC's getFilteredContacts() function declares two required arguments:

<cffunction name="getFilteredContacts" returnType="query"
    access="remote">
  <cfargument name="firstname" type="string" required="true">
  <cfargument name="lastname" type="string" required="true">
  ... function body ...
</cffunction>

Using explicit arguments, you pass values that match the expected data types. This code sends the data in the same order in which they're declared:

contactService.getFilteredContacts(fnameInput.text,
   lnameInput.text);

contactService.getOperation("getFilteredContacts").send(
  fnameInput.text, lnameInput.text);

This calling syntax also works with the WebService component.

Bound arguments are declared in MXML and then passed through a call to the RemoteObject component's send() method. Just as when using the RemoteObject component to call Java-based methods in classes hosted by BlazeDS, you use bound argument notation with XML elements for each argument wrapped in an <mx:arguments> tag set. This code binds the getFilteredContacts() method's two arguments to values gathered from TextInput controls:

<mx:RemoteObject id="contactService" destination="ColdFusion"
  source="flex3bible.chapter26.ContactService">
  <mx:method name="getFilteredContacts">
    <mx:arguments>
      <firstname>{fnameInput.text}</firstname >
      <lastname>{lnameInput.text}</lastname>
    </mx:arguments>
  </mx:method>
</mx:RemoteObject>

To call the method with the bound arguments, call the operation's send() method without any explicit arguments:

contactService.getFilteredContacts.send()

You can match CFC function arguments by name by wrapping them in an ActionScript Object. Each property has a name and a value; the name of the Object property must match the name of the CFC function argument.

This code creates an Object and attaches argument values by name:

var args:Object = new Object();
args.firstname = fnameInput.text;
args.lastname = lnameInput.text;
contactService.getFilteredContacts(args);

You also can write the same code using shorthand Object notation:

contactService.getFilteredContacts(
  {firstname:fnameInput.text, lastname:lnameInput.text});

This behavior is sometimes confusing to ColdFusion developers who first encounter it, because it means that you can't pass an anonymous Object as an argument to a CFC function and expect it to arrive intact as a ColdFusion structure. The Object is always broken down into its named properties, and then the individual properties are passed to the CFC function. If you need to pass a structure argument to a CFC function, you have to wrap it in another Object and pass it by name:

myService.myFunction({myArgumentName:myObject});

The named arguments behavior in Flex is very similar to ColdFusion's own argumentCollection attribute, which can be used to pass a structure of named arguments to functions from CFML code. This CFML code calls a CFC function and passes a structure in very much the same way:

<cfset stArgs=structNew()>
<cfset stArgs.firstname="firstnameValue">
<cfset stArgs.lastname="lastnameValue">
<cfinvoke component="flex3bible.chapter26.ContactService"
  argumentCollection="#stArgs#" returnVariable="qContacts"/>

The application in Listing 26.6 uses named arguments wrapped in an ActionScript Object.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
  backgroundColor="#EEEEEE" xmlns:view="view.*">
  <mx:Script>
    <![CDATA[
      private function getContacts():void
      {
        var args:Object = new Object();
        args.firstname = fnameInput.text;
         args.lastname = lnameInput.text;
contactService.getFilteredContacts(args);
}
]]>
</mx:Script>
<mx:RemoteObject id="contactService" destination="ColdFusion"
     source="flex3bible.chapter26.ContactService"/>
<mx:Form>
     <mx:FormItem label="First Name:">
         <mx:TextInput id="fnameInput"/>
     </mx:FormItem>
     <mx:FormItem label="Last Name:">
       <mx:TextInput id="lnameInput"/>
       <mx:Button label="Get Filtered Data" click="getContacts()"/>
    </mx:FormItem>
  </mx:Form>
<view:ContactsGrid
     dataProvider="{contactService.getFilteredContacts.lastResult}"/>
</mx:Application>

The ColdFusion version of a value object is written as a simple CFC. The <cfcomponent> start tag requires an alias attribute that's set to the fully qualified name and location of the CFC:

<cfcomponent output="false" alias="flex3Bible.chapter26.Contact">
     ... component body ...
</cfcomponent>

Each named property is declared after the <cfcomponent> start tag using the <cfproperty> tag. Each property has a name and a type to indicate how it will be exchanged with Flex. The following <cfproperty> tags declare one numeric and two string properties:

<cfproperty name="contactId" type="numeric" default="0">
<cfproperty name="firstname" type="string" default="">
<cfproperty name="lastname" type="string" default="">

The <cfproperty> tag's default attribute is used to generate CFC documentation and doesn't actually set default values when the CFC is instantiated in ColdFusion. Instead, you typically add code outside any function definitions that set the properties' default values upon instantiation:

<cfscript>

     this.contactId = 0;
     this.firstname = "";
     this.lastname = "";
</cfscript>

The CFC in Listing 26.7 is a value object that declares four properties of a Contact value object and sets their initial values upon instantiation.

<cfcomponent output="false" alias="flex3Bible.chapter26.Contact">
     <cfproperty name="contactId" type="numeric" default="0">
     <cfproperty name="firstname" type="string" default="">
     <cfproperty name="lastname" type="string" default="">
     <cfproperty name="city" type="string" default="">
     <cfscript>
          this.contactId = 0;
          this.firstname = "";
          this.lastname = "";
          this.city = ""
   </cfscript>
</cfcomponent>

The Flex client application uses an ActionScript version of the value object built as an ActionScript class. The class requires a [RemoteClass] metadata tag with an alias attribute that describes the fully qualified name and location of the matching CFC:

[RemoteClass(alias="flex3Bible.chapter26.Contact")]

This is a two-way mapping: When an ActionScript version of the object is sent to ColdFusion, the Flash Remoting gateway creates an instance of the CFC and passes the received object's property values to the server-side version. Similarly, if a CFC function returns instances of the server-side version, client-side versions are created automatically and their property values set to the values received from the server.

The ActionScript class in Listing 26.8 declares the same set of values as public properties and maps itself to the server's version with the [RemoteClass] metadata tag.

package vo
{
  [Bindable]
  [RemoteClass(alias="flex3Bible.chapter26.Contact")]
  public class Contact
  {
    public var contactId:int;
    public var firstname:String;
    public var lastname:String;
    public var city:String;
    public function Contact()
    {
    }
  }
}

After you've built versions of the value object in both ColdFusion and ActionScript and provided the appropriate mappings, a CFC function has the ability to return either individual value object instances or collections of value objects wrapped into arrays. This CFC function creates an instance of the Contact value object and returns it to Flex:

<cffunction name="getContactVO" access="remote"
     returntype="flex3Bible.chapter26.Contact">
     <cfset contact=createObject("component",
          "flex3Bible.chapter26.Contact")>
     <cfset contact.contactId = 1 >
     <cfset contact.firstname = "David">
     <cfset contact.lastname = "Gassner">
     <cfset contact.city = "Seattle">
     <cfreturn contact>
</cffunction>

Notice that the function's returntype attribute is set to the fully qualified name and location of the value object CFC.

The CFC in Listing 26.9 extends the original CFC and uses its data, but transforms the query object into an array of strongly typed value objects before returning it to Flex. Notice that this time the CFC function's returntype attribute is set to an array of CFC instances, rather than the usual generic array notation.

<cfcomponent name="ContactServiceWithVO"
    hint="Delivers Contact data as an array of value objects"
    extends="ContactService">
    <cfapplication name="flex3BibleChapter26"
                                          sessionManagement="true">
    <cfif not structKeyExists(session, "qContacts")>
    <cfset createDataSet()>
    </cfif>
    <!--- Returns all data as an array of structures --->
    <cffunction name="getContactsAsArray" access="remote"
    returntype="flex3Bible.chapter26.Contact[]">
    <cfset var contact="">
    <cfset var arReturn=arrayNew(1)>
    <cfloop query="session.qContacts">
      <cfset contact=createObject("component",
         "flex3Bible.chapter26.Contact")>
    <cfset contact.contactId = session.qContacts.contactId>
    <cfset contact.firstname = session.qContacts.firstname>
    <cfset contact.lastname = session.qContacts.lastname>
    <cfset contact.city = session.qContacts.city>
    <cfset arrayAppend(arReturn, contact)>
     </cfloop>
     <cfreturn arReturn>
   </cffunction>
</cfcomponent>

In order to receive value objects from a CFC function and have them automatically transformed into instances of the ActionScript value object, the Flex application must contain at least one reference to the ActionScript class. The reference can be a declared instance of the class or a call to any static properties or methods. This ensures that the class, which contains the [RemoteClass] metadata tag, is compiled into the application and is available at runtime.

The Flex application in Listing 26.10 receives the Array of value objects and processes them in an event handler. Notice the MXML <vo:Contact/> declaration that ensures the mapping of the value object classes is included in the compiled application.

contactData.source = event.result as Array;

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    backgroundColor="#EEEEEE" creationComplete="initApp()"
    xmlns:view="view.*" xmlns:vo="vo.*">
    <mx:Script>
    <![CDATA[
    import mx.controls.Alert;
    import mx.collections.ArrayCollection;
    import mx.rpc.events.ResultEvent;
    import mx.rpc.remoting.RemoteObject;
    [Bindable]
    private var contactData:ArrayCollection = new ArrayCollection();
    private var contactService:RemoteObject;
    private function initApp():void
    {
    contactService = new RemoteObject("ColdFusion");
    contactService.source =
      "flex3bible.chapter26.ContactServiceWithVO";
    contactService.addEventListener(ResultEvent.RESULT,
      resultHandler);
    }
    private function resultHandler(event:ResultEvent):void
    {
    contactData.source = event.result as Array;
    }
    ]]>
    </mx:Script>
    <vo:Contact/>
    <mx:Button label="Get Contacts"
    click="contactService.getContactsAsArray()"/>
    <view:ContactsGrid dataProvider="{contactData}"/>
</mx:Application>

Value objects also can be passed from a Flex client application to a CFC function. The CFC function should have declared an argument typed as the ColdFusion version of the value object. This CFC function receives an instance of the Contact value object CFC and returns a concatenated string built from its properties:

<cffunction name="parseContact" access="remote">'
    <cfargument name="contactVO"
      type="flex3Bible.chapter26.Contact"
    required="true">
    <cfreturn "Contact received: " + contactVO.firstname +
    " " + contactVO.lastname>
</cffunction>

To pass a value object argument to the CFC function from Flex, create an instance of the ActionScript version of the object and set its properties. Then pass the value object to the function using any of the argument-passing strategies described previously.

The application in Listing 26.11 passes an instance of the ActionScript value object to a CFC function that extracts its properties and returns a concatenated string.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    backgroundColor="#EEEEEE">
    <mx:Script>
    <![CDATA[
      import vo.Contact;
      private function passArgument():void
      {
        var newContact:Contact = new Contact();
        newContact.firstname = fnameInput.text;
        newContact.lastname = lnameInput.text;
        contactService.parseContact(newContact);
      }
    ]]>
    </mx:Script>
    <mx:RemoteObject id="contactService" destination="ColdFusion"
    source="flex3bible.chapter26.ContactServiceWithVO"/>
    <mx:Panel title="Enter Contact Information">

<mx:Form>
      <mx:FormItem label="First Name:">
        <mx:TextInput id="fnameInput"/>
      </mx:FormItem>
      <mx:FormItem label="Last Name:">
        <mx:TextInput id="lnameInput"/>
        <mx:Button label="Pass Argument" click="passArgument()"/>
      </mx:FormItem>
    </mx:Form>
    </mx:Panel>
    <mx:Label text="{contactService.parseContact.lastResult}"
    fontSize="12"/>
</mx:Application>

As with all events, you can create an event listener with either MXML or ActionScript code. The MXML attribute-based event listener looks like this:

<mx:RemoteObject id="contactService" destination="ColdFusion"
       source="flex3bible.chapter26.ContactServiceWithVO"
       fault="faultHandler(event)"/>

To create an event listener in ActionScript code, call the RemoteObject component's addEventListener() method and declare the event name using the FaultEvent.FAULT constant:

faultService.addEventListener(FaultEvent.FAULT, faultHandler);

When the event handler function receives the event object, you can handle it in any way you like. Minimally, you might display the fault information to the user with a pop-up dialog box generated by the Alert class:

private function faultHandler(event:FaultEvent):void
     {
       Alert.show(event.fault.faultString, event.fault.faultCode);
}

var errorMessage:String = event.fault.faultString;
errorMessage = errorMessage.substring(22,
      errorMessage.length);
Alert.show(errorMessage, event.fault.faultCode);

On the server, you can generate your own faults from a CFC function by calling the ColdFusion <cfthrow> command. These <cfthrow> commands' attributes are exposed in the Flex application's <FaultEvent.fault> object:

The CFC in Listing 26.12 implements a throwCFCFault() function that always generates a fault with message and errorcode attributes.

<cfcomponent output="false">
    <cffunction name="throwCFCFault" returntype="String">
    <cfthrow message="An error message generated by a CFC function"
      errorcode="CFC Function Error">
    <cfreturn "A String">
    </cffunction>
</cfcomponent>

The Flex application in Listing 26.13 calls the CFC function to intentionally generate a fault and display its information in an Alert pop-up dialog box.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    backgroundColor="#EEEEEE">
    <mx:Script>
    <![CDATA[
      import mx.controls.Alert;
      import mx.rpc.events.FaultEvent;
      import mx.rpc.events.ResultEvent;
      import mx.rpc.remoting.RemoteObject;
      [Bindable]
      private var returnString:String;
      private function resultHandler(event:ResultEvent):void
      {
       returnString = event.result as String;
      }
      private function faultHandler(event:FaultEvent):void
      {
        var errorMessage:String = event.fault.faultString;
        errorMessage = errorMessage.substring(22, errorMessage.length);
        Alert.show(errorMessage, event.fault.faultCode);      }
    ]]>
    </mx:Script>
    <mx:RemoteObject id="faultService" destination="ColdFusion"
    source="flex3bible.chapter26.FaultService"
    result="resultHandler(event)"
    fault="faultHandler(event)"/>
    <mx:Button label="Generate Fault"
      click="faultService.throwCFCFault()"/>
    <mx:Label text="{returnString}"/>
</mx:Application>