| Developing ColdFusion MX Applications with CFML |
|
|
Handling Errors |
|
| Developing ColdFusion MX Applications with CFML |
|
|
Handling Errors |
|
There are many ways to look at errors; for example, you can look at errors by their causes. You can also look at them by their effects, particularly by whether your application can recover from them. You can also look at them the way ColdFusion does. The following sections discuss these ways of looking at errors.
Errors can have many causes. Depending on the cause, the error might be recoverable. A recoverable error is one for which your application can identify the error cause and take action on the problem. Some errors, such as time-out errors, might be recoverable without indicating to the user that an error was encountered. An error for which a requested application page does not exist is not recoverable, and the application can only display an error message.
Errors such as validation errors, for which the application cannot continue processing the request, but can provide an error-specific response, can also be considered recoverable. For example, an error that occurs when a user enters text where a number is required can be considered recoverable, because the application can recognize the error and redisplay the data field with a message providing information about the error's cause and telling the user to reenter the data.
Some types of errors might be recoverable in some, but not all circumstances. For example, your application can retry a request following a time-out error, but it must also be prepared for the case where the request always times out.
Error causes fall in the broad categories listed in the following table:
| Category |
Description |
|---|---|
| Program errors |
Can be in the code syntax or the program logic. The ColdFusion compiler identifies and reports program syntax errors when it compiles CFML into Java classes. Errors in your application logic are harder to locate. For information on debugging tools and techniques, see Chapter 18, "Debugging and Troubleshooting Applications". Unlike ColdFusion syntax errors, SQL syntax errors are only caught at runtime. |
| Data errors |
Are typically user data input errors. You use validation techniques to identify errors in user input data and enable the user to correct the errors. |
| System errors |
Can come from a variety of causes, including database system problems, time-outs due to excessive demands on your server, out-of-memory errors in the system, file errors, and disk errors. |
Although these categories do not map completely to the way ColdFusion categorizes errors they provide a useful way of thinking about errors and can help you in preventing and handling errors in your code.
Before you can effectively manage ColdFusion errors, you must understand how ColdFusion classifies and handles them. ColdFusion categorizes errors as detailed in the following table:
| Type |
Description |
|---|---|
| Exception |
An error that prevents normal processing from continuing. All ColdFusion exceptions are, at their root, Java exceptions. |
| Missing template |
An HTTP request for a ColdFusion page that cannot be found. Generated if a browser requests a ColdFusion page that does not exist. Missing template errors are different from missing include exceptions, which result from cfinclude tags or custom tag calls that cannot find their targets. |
| Form field data validation |
User data that does not meet the server-side form field validation rules in a form being submitted. You specify server-side form validation by using hidden HTML form fields. All other types of server-side validation, such as the cfparam tag generate runtime exceptions. For more information on validating form fields see Chapter 27, "Building Dynamic Forms". |
Most ColdFusion errors are exceptions. The following sections describe them in detail.
You can categorize ColdFusion exceptions in two ways:
ColdFusion errors can occur at two times, when the CFML is compiled into Java and when the resulting Java executes, called runtime exceptions.
Compiler exceptions are programming errors that ColdFusion identifies when it compiles CFML into Java. Because compiler exceptions occur before the ColdFusion page is converted to executable code, you cannot handle them on the page that causes them. However, other pages can handle these errors. For more information, see "Handling compiler exceptions"
A runtime exception occurs when the compiled ColdFusion Java code runs. It is an event that disrupts the application's normal flow of instructions. Exceptions can result from system errors or program logic errors. Runtime exceptions include:
cfthrow or cfabort tags
ColdFusion exceptions have types that you specify in the cferror, cfcatch, and cfthrow error-handling tags. A cferror or cfcatch tag will handle only exceptions of the specified type. You identify an exception type by using an identifier from one (or more) of the following type categories:
Note: Use only custom error type names and the Application basic type name in cfthrow tags. All other built-in exception type names identify specific types of system-identified errors, so you should not use them for errors that you identify yourself.
All ColdFusion exceptions except for custom exceptions belong to a basic type category. These types consist of a broadly-defined categorization of ColdFusion exceptions. The following table describes the basic exception types:
Note: The Any type includes all error with the Java object type of java.lang.Exception. It does not include java.lang.Throwable errors. To catch Throwable errors, specify java.lang.Throwable in the cfcatch tag type attribute.
You can generate an exception with your own type by specifying a custom exception type name, for example MyCustomErrorType, in a cfthrow tag. You then specify the custom type name in a cfcatch or cferror tag to handle the exception. Custom type names must be different from any built-in type names, including basic types and Java exception classes.
The Advanced exceptions consist of a set of specific, narrow exception types. These types are supported in ColdFusion MX for backward-compatibility. For a list of advanced exception types, see CFML Reference.
Every ColdFusion exception belongs to, and can be identified by, a specific Java exception class in addition to its basic, custom, or advanced type. The first line of the stack trace in the standard error output for an exception identifies the exception's Java class.
For example, if you attempt to use an array function such as ArrayIsEmpty on an integer variable, ColdFusion generates an exception that belongs to the Expression exception basic type and the coldfusion.runtime.NonArrayException Java class.
In general, most applications do not need to use Java exception classes to identify exceptions. However, you can use Java class names to catch exceptions in non-CFML Java objects; for example, the following line catches all Java input/output exceptions:
<cfcatch type="java.io.IOException">
The following sections describes briefly how ColdFusion handles errors. The rest of this chapter expands on this information.
If a user requests a page that the ColdFusion cannot find, and the Administrator Server Settings Missing Template Handler field specifies a Missing Template Handler page, ColdFusion uses that page to display error information. Otherwise, it displays a standard error message.
When a user enters invalid data in an HTML tag that uses server-side (hidden form field) data validation, and a cferror tag in the Application.cfm page specifies a Validation error handler, ColdFusion displays the specified error page. Otherwise, it displays the error information in a standard format that consists of a default header, a bulleted list describing the error(s), and a default footer. For more information on using hidden form field validation, see Chapter 26, "Validating form field data types".
If ColdFusion encounters a compiler exception, how it handles the exception depends on whether the error occurs on a requested page or on an included page:
cfinclude or cfmodule tag, or on a custom tag page that you access using the cf_ notation, ColdFusion handles it as a runtime exception in the page that accesses the tag. See the "Runtime exception errors" section, next, for a description of how these errors are handled.
cferror tag on the Application.cfm page specifies an error handler for the exception type, ColdFusion displays the specified error page.
If ColdFusion encounters a runtime exception, it does the action for the first matching condition in the following table:
For example, if an exception occurs in CFML code that is not in a cftry block, but a cferror tag specifies a page to handle this error type, ColdFusion uses the specified error page.