Exception Handling

<cferror> TRaps both parsing and run-time errors. Errors that occur when the template is executed are also called exceptions. Exceptions include any event that disrupts the normal flow of instructions in a ColdFusion page when it is being executed. Exceptions can be more intelligently handled than what you've seen so far using <cferror>.

<cftry>/<cfcatch>

When you use the <cftry>/<cfcatch> tag set, exceptions can be caught and then acted upon programmatically. For instance, instead of throwing an error when attempting to write a duplicate indexed value to a database, ColdFusion can catch the error, then inform the user of the problem and ask him to change the offending data.

The general format of catching an exception in ColdFusion is as follows:

 <cftry>   Possible error producing code <cfcatch type="ExceptionType">   Code to run if error is caught </cfcatch> ...additional <cfcatch></cfcatch> blocks... </cftry> 

CAUTION

It is important to understand that <cftry>/<cfcatch> does not catch syntax errors like <cferror> does. For instance, using a <cftry> block around a <cfquery> tag without a datasource attribute does nothing, because the syntax of the <cfquery> is not correct and the page cannot be parsed correctly. If, on the other hand, the datasource attribute is there but the listed data source does not exist, the <cftry> block catches that exception.

The following is a simple <cftry>/<cfcatch> example. It assumes that a personalized header is included. If for some reason the personalized header is not available, a standard header is displayed.

 <cftry>   <cfinclude template="#Personalized#.cfm">   <cfcatch type="MissingInclude">     <cfinclude template="StandardHeader.cfm">   </cfcatch> </cftry> 

The type attribute in the <cfcatch> tag is the exception type. Table 26.5 lists the possible exception types and the situations in which they are used.

Table 26.5. Exception Types

EXCEPTION TYPE	DESCRIPTION
Any	All exceptions are caught.
Application	Custom exception types using <cfthrow> without specifying a custom type.
Custom Type	Custom exception types using <cfthrow> and specifying a custom type fail.
Database	Database operations fail.
Expression	Expression evaluation fails.
Lock	Locking operations fail.
MissingInclude	Included files cannot be found.
Object	Code using <cfobject> fails.
Template	General application page errors are returned.
SearchEngine	Verity search engine exceptions are returned.
Security	Code using ColdFusion security fails.

<cfcatch> Variables

When an error is caught, you should attempt to "fix" it in the <cfcatch> blockthat is, programmatically supply a solution to the problem. This task is made easier by the variables available in the scope of the <cfcatch> block. A set of variables is defined for all exception types. Other variables exist only for certain exception types. Those variables that are defined for all exception types are listed in Table 26.6.

Table 26.6. Variables Defined for All Exception Types

VARIABLE	DESCRIPTION
Detail	A message from the CFML interpreter. Here, you can see which tag threw the exception.
Message	The exceptions message.
Type	The exception type as specified in <cfcatch>.

<cfthrow>

In some cases, it is advantageous to centralize exception handling. For instance, you might have a page that calls a number of custom tags. Rather than deal with exceptions in detail on every custom tag, you could simply throw the error back to the calling page in all cases and deal with the exceptions in detail there.

To do so, you can use the <cfthrow> tag, which is a useful tool. The attributes available when using <cfthrow> are listed in Table 26.7.

Table 26.7. <cfthrow> Tag Attributes

ATTRIBUTE	DESCRIPTION
detail	Detailed information you select.
errorcode	An error code you select.
extendedinfo	Extended information you select.
message	A message you select.
object	Java object to which to throw the exception to.
type	The custom exception type you name. This attribute is optional.

For an example of <cfthrow>, consider a custom tag that checks inventory against the quantity ordered, as shown in the following code. If the inventory is less than the quantity ordered, an exception is raised.

 <cfif Ordered GTE Inventory>   <cfthrow type="Reorder"            message="Reorder product #ProdName#"            extendedinfo="#Now()#" </cfif> 

This code uses a custom exception type named Reorder. You also can see that the message and extendedinfo attributes pass back to the calling page the name of the product to reorder and the time stamp indicating when the exception was thrown.

If the name of the custom tag with this code were called PlaceOrder.cfm, you could call it in a <cftry> block as follows:

 <cftry>   <cf_PlaceOrder>   <cfcatch type="Reorder">     <cfoutput>     #CFCATCH.Message#.     The alert occurred at #CFCATCH.ExtendedInfo#.     </cfoutput>   </cfcatch> </cftry> 

NOTE

If the type attribute were not used in <cfthrow>, you could have caught the exception by using type="Application" in <cfcatch>. The purpose of the Application type is to catch exceptions from <cfthrow> when a type is not specified.

<cfthrow> can also be used to throw exceptions to a Java object. If object is used, no other <cfthrow> attributes are used.

<cfrethrow>

In some cases, you might want to throw the exact error that occurred. For instance, suppose a database error occurs on a custom tag, and you want to throw that exact error to the calling page and deal with it in that location. The <cfrethrow> tag does this job. Using this tag saves you from having to build a custom type and supply the appropriate values for the message, detail, errorcode, and extendedinfo attributes. Assume the following code is in a custom tag called MyInsert.cfm:

 <cftry>   Some database action performed here, for example an insert   <cfcatch type="Database">     <cfrethrow>   </cfcatch> </cftry> 

You then can handle the call to the custom tag like this:

 <cftry>   <CF_MyInsert>     <cfcatch type="Database">       Database error occurred!       <cfoutput>The error code is #CFCATCH.SQLState#</cfoutput>    </cfcatch> </cftry> 

This code shows that the exact error originally thrown on the custom tag (in this example, of type Database) can be caught on the calling page.

Exceptions in <cfscript>

Code written in <cfscript> can also implement exception handling via the try and catch keywords. <cfscript> does not support throw and rethrow.

As with <cftry>, every try must have a matching catch. Within the catch code, a variable named exceptionvariable contains the information exposed by CFCATCH.type, explained previously.