You can use the cfthrow tag to raise your own, custom exceptions. When you use the cfthrow tag, you specify any or all of the following information:
Attribute |
Meaning |
---|---|
type |
The type of error. It can be a custom type that has meaning only to your application, such as InvalidProductCode. You can also specify Application, the default type. You cannot use any of the predefined ColdFusion error types, such as Database or MissingTemplate. |
message |
A brief text message indicating the error. |
detail |
A more detailed text message describing the error. |
errorCode |
An error code that is meaningful to the application. This field is useful if the application uses numeric error codes. |
extendedInfo |
Any additional information of use to the application. |
All of these values are optional. You access the attribute values in cfcatch blocks and Exception type error pages by prefixing the attribute with either cfcatch or error, as in cfcatch.extendedInfo. The default ColdFusion error handler displays the message and detail values in the Message pane and the remaining values in the Error Diagnostic Information pane.
Catching and displaying thrown errors
The cfcatch tag catches a custom exception when you use any of the following values for the cfcatch type attribute:
Similarly, if you specify any of these types in a cferror tag, the specified error page will display information about the thrown error.
Because the cfthrow tag generates an exception, a Request error handler or the Site-wide error handler can also display these errors.
Custom error type name hierarchy
You can name custom exception types using a method that is similar to Java class naming conventions: domain name in reverse order, followed by project identifiers, as in the following example:
<cfthrow type="com.myCompany.myApp.Invalid_field.codeValue" errorcode="Dodge14B">
This fully qualified naming method is not required; you can use shorter naming rules, for example, just myApp.Invalid_field.codeValue, or even codeValue.
This naming method is not just a convention; ColdFusion uses the naming hierarchy to select from a possible hierarchy of error handlers. For example, assume you use the following cfthrow statement:
<cfthrow type="MyApp.BusinessRuleException.InvalidAccount">
Any of the following cfcatch error handlers would handle this error:
<cfcatch type="MyApp.BusinessRuleException.InvalidAccount"> <cfcatch type="MyApp.BusinessRuleException"> <cfcatch type="MyApp">
The handler that most exactly matches handles the error. In this case, the MyApp.BusinessRuleException.InvalidAccount handler gets invoked. However, if you used the following cfthrow tag:
<cfthrow type="MyApp.BusinessRuleException.InvalidVendorCode
the MyApp.BusinessRuleException handler receives the error.
The type comparison is not case-sensitive.
Use the cfthrow tag when your application can identify and handle application-specific errors. One typical use for the cfthrow tag is in implementing custom data validation. The cfthrow tag is also useful for throwing errors from a custom tag page to the calling page.
For example, on a form action page or custom tag used to set a password, the application can determine whether the password entered is a minimum length, or contains both letters and number, and throw an error with a message that indicates the password rule that was broken. The cfcatch block handles the error and tells the user how to correct the problem.