There may be occasions when a CFC function being used by Flex needs to throw a custom exception to alert the caller of the function that some problem has occurred during the function (1). If you're using Flex to call a CFC function that may throw an exception then you need a way to handle the exception in Flex (6) and display an appropriate error message to the user. This blog entry desribe a technique I use to throw an exception from a CFC function and then display an exception message in Flex to the user. Flex automatically translates the attributes of the ColdFusion cfthrow tag (3) to property values of the Flex Fault class (8).
ColdFusion provides the cfthrow tag (2), which has several attributes that you can use to provide information about the exception being thrown. You can use the message attribute to provide a brief description of the problem, the detail attribute to provide a more detailed description, the type attribute to indicate a specific custom exception type, and the errorCode attribute to specify a error number that corresponds to the problem.
<cfthrow type="CreditCardException.AuthorizationNotAvaialable" errorcode="9"
detail="Could not connect to the credit card authorization site. Please try again later.
The system administrator has been notified about the problem."
message="Credit card verification site unavailable."
When using the mx:RemoteObject tag (4,5) in Flex to call a ColdFusion CFC you can specify an ActionScript function to be called should the CFC generate an exception (6). For example:
If the processCreditCard method generates an exception, Flex will automatically call the function specified as the value for the mx:method tag's fault attribute. In the above example, that function called will be the faultProcessCreditCard function. Flex will pass to this function an object of type FaultEvent (7). The FaultEvent object has a public property named fault, which is of type Fault (8). The Fault class (8) has several properties that will be populated with values from the exception thrown by the CFC function. This table shows which attribute of the ColdFusion cfthrow tag is used to provide the value for which Flex Fault property.
|cfthrow attribute||Flex Fault property|
One thing to note is that Flex will add to the message attribute's value the text "Unable to invoke CFC". So a cfthrow tag's message attribute with a value of "Credit card verification site unavailable" will become "Unable to invoke CFC - Credit card verification site unavailable" in the faultString property. Thus the faultString property value isn't one you probably want to display to the user of your Flex application.
Usually, I give the cfthrow's detail attribute a value that will be the explanation of the problem I want the user to see in my Flex application. Then in the function of my Flex application that was specified to handle the exception (eg, faultProcessCreditCard function) I use the Alert control to show the user the value of the faultDetail property. For example:
Alert.show(event.fault.faultDetail,"An Error Has Occurred" );
Another technique I've used is to change the state of the Flex application and display the value of the faultDetail property as a part of a mx:Text component. See reference 9 for an example of this technique.
One important point is that all exceptions generated by calling the CFC function will be handled by calling the same Flex function. If the CFC function needs to throw different types of exceptions, then you could use multiple cfthrow tags. If you give each cfthrow tag its own errorCode value, you can then use logic within the Flex function to do different actions depending on the value of the Fault class faultCode property.
You can view a complete example of handling in Flex an exception generated by a CFC function (10). Right click on the Flex application and select view source to see the source code.
- Handling Errors, ColdFusion Developer's Guide
- Using the cfthrow tag, ColdFusion Developer's Guide
- cfthrow, CFML Reference
- Using RemoteObject Components, Data Access and Interconnectivity
- RemoteObject, Adobe Flex 3 Language Reference
- Handling Service Results, Data Access and Interconnectivity
- FaultEvent, Adobe Flex 3 Language Reference
- Fault, Adobe Flex 3 Language Reference
- Handle Registration Errors, Bruce Phillips' Blog
- Handle CFC Exception Example