Description

Throws a developer-specified exception, which can be caught with a cfcatch tag that has any of the following type attribute options:

  • type = "custom_type"
  • type = "Application"
  • type = "Any"

Category

Syntax

message = "message"
type = "exception type"
detail = "detail description"
errorCode = "error code"
extendedInfo = "additional information"
object = "java except object">

OR

<cfthrow
object = #object_name#>

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

See also

cferrorcfrethrowcftryonErrorHandling Errors in the Developing ColdFusion Applications

History

ColdFusion MX: Changed thrown exceptions: this tag can throw ColdFusion component method exceptions.

Attributes

Attribute

Req/Opt

Default

Description

detail

Optional

 

Description of the event. ColdFusion appends error position to description; server uses this parameter if an error is not caught by your code.

errorCode

Optional

 

A custom error code that you supply.

extendedInfo

Optional

 

A custom error code that you supply.

message

Optional

 

Message that describes exception event.

object

Optional

 

Requires the value of the cfobject tag name attribute.
Throws a Java exception from a CFML tag.
This attribute is mutually exclusive with all other attributes of this tag.

type

Optional

Application

  • A custom type
  • Application
    Do not enter another predefined type; types are not generated by ColdFusion applications. If you specify Application, you need not specify a type for cfcatch.

Usage

Use this tag within a cftry block, to throw an error. The cfcatch block can access accompanying information, as follows:

  • Message, with cfcatch.message
  • Detail, with cfcatch.detail
  • Error code, with cfcatch.errorcode To get more information, use cfcatch.tagContext. This array shows where control switches from one page to another in the tag stack (for example, cfinclude, cfmodule).
    To display the information displayed by tagContext variable, select the "Enable Robust Exception Information" option on the Debugging & Logging > Debug Output Settings page of the ColdFusion Administrator.
    To use this tag with the object parameter, first use a cfobject tag that specifies a valid Java exception class. For example, the following cfobjecttag defines an object, obj, of the exception class myException (which you must create in Java):

type="java"
action="create"
class="myException"
name="obj">

If your exception class has constructors that take parameters, such as a message, you can use the special initmethod to invoke the constructor, as in the following line. If you do not need to specify any constructor attributes, you can omit this step.

<cfset obj.init("You must save your work before preceding")>

You can then use the, the cfthrowstatement to throw the exception as follows:

<cfthrow object=#obj#>

For more information on using Java objects in ColdFusion, see Integrating JEE and Java Elements in CFML Applications in the Developing ColdFusion Applications.

Example

<h3>cfthrow Example</h3> 
<!--- Open a cftry block. ---> 
<cftry> 
<!--- Define a condition upon which to throw the error. ---> 
<cfif NOT IsDefined("URL.myID")> 
<!--- throw the error ---> 
<cfthrow message = "ID is not defined"> 
</cfif> 
<!--- Perform the error catch. ---> 
<cfcatch type = "application"> 
<!--- Display your message. ---> 
<h3>You've Thrown an <b>Error</b></h3> 
<cfoutput> 
<!--- And the diagnostic feedback from the application server. ---> 
<p>#cfcatch.message#</p> 
<p>The contents of the tag stack are:</p> 
<cfloop 
index = i 
from = 1 to = #ArrayLen(cfcatch.tagContext)#> 
<cfset sCurrent = #cfcatch.tagContext[i]#> 
<br>#i# #sCurrent["ID"]# 
(#sCurrent["LINE"]#,#sCurrent["COLUMN"]#) 
#sCurrent["TEMPLATE"]# 
</cfloop> 
</cfoutput> 
</cfcatch> 
</cftry>

The following example shows how to throw an exception from a component method:

<cffunction name="getEmp">
<cfargument name="lastName" required="yes">
<cfquery name="empQuery" datasource="cfdocexamples" >
SELECT LASTNAME, FIRSTNAME, EMAIL
FROM tblEmployees
WHERE LASTNAME LIKE '#arguments.lastName#'
</cfquery>
<cfif empQuery.recordcount LT 1>
<cfthrow type="noQueryResult"
message="No results were found. Please try again.">
<cfelse>
<cfreturn empQuery>
</cfif>
</cffunction>
</cfcomponent>

For an explanation of the example and more information, see Building and Using ColdFusion Components in the Developing ColdFusion Applications.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy