object = "java_except_object">
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
    <cfthrow 
   type = "exception_type "
   message = "message"
   detail = "detail_description "
   errorCode = "error_code "
   extendedInfo = "additional_information"

  
 
Syntax
    <cfthrow 
   object = #object_name#>

  
 
See also

cferror, cfrethrow, cftry

 
History

New in ColdFusion MX: this tag can throw ColdFusion component method exceptions.

 
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 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 Administrator, Debugging page, select Enable CFML Stack Trace.

To use this tag with the object parameter, you must define an exception using the cfobject tag, with code such as the following:

<cfobject 
type="java" 
action="create" 
class="coldfusion.tagext.InvalidTagAttributeException" 
name="obj">
<cfset obj.init("Attribute", "value")>

With this code, the cfthrow statement would be as follows:

<cfthrow object=#obj#>

The cfthrow tag passes exception parameters to the obj variable.

 
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>
TYPE  
  Optional
 
Default value: "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.

MESSAGE  
  Optional
 

Message that describes exception event.

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.

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.