cfthrow

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

Exception handling tags, Flow-control tags

Syntax 1

<cfthrow 
   type = "exception_type "
   message = "message"
   detail = "detail_description "
   errorCode = "error_code "
   extendedInfo = "additional_information"
   object = "java_except_object">

Syntax 2

<cfthrow 
   object = #object_name#>

See also

cferror, cfrethrow, cftry, onError; Handling Errors in ColdFusion MX Developer's Guide

History

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

Attributes

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: in the ColdFusion MX Administrator, Debugging page, select Enable CFML Stack Trace.

Using the object parameter To use this tag with the object parameter, you must first use a cfobject tag that specifies a valid Java exception class. For example, the following cfobject tag defines an object, obj, of the exception class myException (which you must create in Java):

<cfobject 
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 init method 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 cfthrow statement to throw the exception as follows:

<cfthrow object=#obj#>

For more information on using Java objects in ColdFusion, see Integrating J2EE and Java Elements in CFML Applications in ColdFusion MX Developer's Guide.

Example 1

<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>

Example2

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

<cfcomponent>
   <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 ColdFusion MX Developer's Guide.

View comments in LiveDocs