Error Handling With Fusebox Presentation By Eron Cohen

What We’ll Learn l How to handle Errors with Cold. Fusion: l l l CFERROR CFTRY/CFCATCH/CFTHROW A little bit about the Fusebox method of writing Cold. Fusion applications l l How does it work? Why is it so good for catching and logging errors?

CFERROR vs. CFTRY l l l l There are two basic ways to handle errors with CFML: CFERROR and CFTRY is more flexible than CFERROR is a bit easier because its more “cut and dry. ” With CFERROR processing usually stops when you throw an error, with CFTRY, processing can continue. CFTRY allows for a finer level of control than CFERROR. CFTRY allows you to handle the error on the same template that threw the error. For a Fusebox application, you’ll probably want to use CFTRY. CFERROR isn’t as flexible and doesn’t lend itself to FUSEBOX as well.

How To Use CFERROR The CFERROR tag is normally used in the APPLICATION. CFM file so that it will be included at the top of every Cold Fusion template. Syntax: <CFERROR TYPE="Request" or "Validation" or "Monitor" or "Exception" TEMPLATE="path" MAILTO="email_address" EXCEPTION="exception_type"> If an error is thrown during the execution of a page that is within the realm of your APPLICATION. CFM, the template that you specified will execute. Depending on what type of CFERROR you specify, there are certain restrictions on how you can handle the error. For instance, if you specify the type “REQUEST”, your error handling template cannot contain any CFML tags…it can only output a predetermined list of variables combined with HTML. On the other hand, if you specify the type “Exception” you’ll have the ability to utilize the fullrange of CFML functions.

Example of how to use CFERROR APPLICATION. CFM: <cfif IP is not “ 127. 0. 0. 1"> <CFERROR TYPE="REQUEST" TEMPLATE=" REQUESTERR. CFM " MAILTO="eron@in-sync. com"> <CFERROR TYPE="VALIDATION" TEMPLATE="Validation. Err. cfm"> </cfif> REQUESTERR. CFM: There was an error: <p> Date/Time: #Error. Date. Time# IP Address: #Error. Remote. Address# Referring Page: # Error. HTTP_REFERER# Offending Script: #error. script_name#"

How to Use CFTRY/CFCATCH For every <CFTRY></CFTRY> pair, there needs to be at least one <CFCATCH></CFCATCH>. The syntax is something like: <CFTRY>. . . Add code here. <CFCATCH TYPE="exceptiontype">. . . Add exception processing code here. </CFCATCH> <CFCATCH TYPE="exceptiontype">. . . Add exception processing code here </CFCATCH> </CFTRY>

Types of Exceptions Used With CFCATCH These are the types of exceptions you can specify in your CFCATCH statement: Application, Database, Template, Security, Object, Missing. Include, Expression, Lock, Custom_type, Any (default). – – – You can have multiple CFCATCHES to handle different types of errors. Cold. Fusion tests CFCATCH types in the ORDER THEY APPEAR on your page! Type=“Any” is the catch all. It will execute in the face of any type of error. Put that one at the end of your block of CFCATCHES (or if you only specify one CFCATCH, use this one!). Also keep in mind that they really do mean “ANY!” kind of error. If an error is thrown for a type of error that has no CFCATCH to handle it, it will throw its default error. The “Custom” and “Application” types of errors are used with the CFTHROW tag.

Variables Exposed to CFCATCH A CFCATCH block may contain certain informational variables. Here a few of them: l l l l l Type -- Exception type, as specified in CFCATCH. Message -- The exception's diagnostic message, if one was provided. If no diagnostic message is available, this is an empty string. Detail -- A detailed message from the CFML interpreter. This message, which contains HTML formatting, can help determine which tag threw the exception. Tag. Context -- The tag stack: the name and position of each tag in the tag stack, and the full path names of the files that contain the tags in the tag stack. See the note that follows this list for more information. Native. Error. Code -- TYPE=Database only. The native error code associated with this exception. Database drivers typically provide error codes to assist diagnosis of failing database operations. If no error code was provided, the value of Native. Error. Code is -1. SQLSTATE -- TYPE=Database only. The SQLState associated with this exception. Database drivers typically provide error codes to assist diagnosis of failing database operations. If no SQLState value was provided, the value of SQLSTATE is -1. Err. Number -- TYPE=Expression only. Internal expression error number. Missing. File. Name -- TYPE=Missing. Include only. Name of the file that could not be included. Error. Code -- TYPE=Custom type only. A string error code. Extended. Info -- TYPE=APPLICATION and custom only. A custom error message.

Leverage Your Error Handling with CFTHROW l l l Now that you’ve designed such great error handlers, why not recycle them using CFTHROW? When a condition occurs in your application, that normally would not throw a Cold. Fusion error, you can “simulate” one with CFTHROW allows you to send Cold. Fusion to one of three kinds of CFCATCH error handlers: l l l CFCATCH TYPE= "custom_type " CFCATCH TYPE= "APPLICATION " CFCATCH TYPE= "ANY " Syntax: <CFTHROW TYPE= "exception_type " MESSAGE="message" DETAIL= "detail_description " ERRORCODE= "error_code " EXTENDEDINFO= "additional_information ">

A Brief Explanation of Fusebox The Fusebox method is simply a style of writing code as a “circuit application. ” Depending what “fuseaction” is specified, a different CFSWITCH is thrown. l Code is modular so it is easy to reuse. l Code is self-documenting and easier to read. l Code is written to a documented standard so the next time someone works on the code it will be easy to understand.

A Simple Fusebox Example INDEX. CFM: <CFINCLUDE TEMPLATE="app_locals. cfm"> <CFSWITCH expression="#attributes. fuseaction#"> <CFCASE value=“Sign_Up_For_Newsletter_Form"> <CFINCLUDE template="/public/Main/blocks/dsp_html_header. cfm"> <CFINCLUDE template="/public/Newsletter/blocks/dsp_reg_form. cfm"> <CFINCLUDE template="/public/Main/blocks/dsp_html_footer. cfm"> </CFCASE> <CFCASE value=“Sign_Up_For_Newsletter_Form_Submitted"> <CFINCLUDE template="/public/Main/blocks/dsp_html_header. cfm"> <CFINCLUDE template="/public/Newsletter/queries/qry_chk_for_dups. cfm"> <CFINCLUDE template="/public/Newsletter/blocks/dsp_reg_thnk_you. cfm"> <CFINCLUDE template="/public/Main/blocks/dsp_html_footer. cfm"> </CFCASE> </CFSWITCH>

Fusebox is perfect for trapping errors! l l One of the great things about the Fusebox methodology is that all actions for the entire application are controlled through one file: your main index. cfm. This means that if you want to trap errors you have a single point of attack to do so. Lets look at my example index. cfm printout…

Gotchas & Mentionables l l l Gotcha: In Cold. Fusion 4. 5 and before, the error handling templates for CFERROR cannot contain any CFML, just a few predetermined variables! Later versions of Cold. Fusion have added flexibility for some types of CFERRORs. Gotcha: Make sure you don’t have any errors in your CFCATCH exceptions are not handled by the CFTRYs that enclose it. Mentionable: You can customize your default Cold Fusion and Web server error messages. Sick of seeing ugly white screen 404 errors? You can substitute your own in the webserver software. Cold Fusion Administrator also provides a preference setting for handling problems:

Creative ways to use CFTRY/CFCATCH l l l We log any errors that occur on our website in a database for review at a later time. It means we don’t have to rely on an end user to describe what happened. Problem with CFPOP solved by CFTRY Big Query/little query