cfthrow

Description

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

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

History

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

Attributes

Attribute Req/Opt Default Description
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.
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.

Usage

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

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>

Comments