Defining the application and its event handlers in Application.cfc

Search
ColdFusion

ColdFusion

Open app

The Application.cfc file defines application-wide settings and variables, and application event handlers:

  • Application-wide settings and variables include page processing settings, default variables, data sources, style settings, and other application-level constants.
  • Application event handlers are CFC methods that ColdFusion automatically executes when specific events occur during the lifetime of an application: application start and end, session start and end, request start, execution, and end, and exceptions.

Defining application-level settings and variables

When you create an application, you can set many application-wide properties and characteristics, including the following items:

  • Application name
  • Application properties, including Client-, Application-, and Session-variable management options
  • Page processing options
  • Default variables, data sources, style settings, and other application-level constants
    For information on setting default variables, see Setting application default variables and constants in onApplicationStart  in this page.

Naming the application

Define the application and give it a name by setting the This.name variable in the Application.cfc initialization section, before the method definitions. By using a specific application name, you define a set of pages as part of the same logical application. 
ColdFusion supports unnamed applications, which are useful for ColdFusion applications that must interoperate with JSP tags and servlets. Consider creating an unnamed application only if your ColdFusion pages must share Application or Session scope data with existing JSP pages and servlets. You cannot have more than one unnamed application on a server instance. For more information on using unnamed applications, see Sharing data between ColdFusion pages and JSP pages or servlets in Interoperating with JSP pages and servlets.

Setting application properties

Specify application properties by setting  This scope variables  in the Application.cfc initialization code. (These are the same properties that you set in the  cfapplication  tag.) The following table lists  the This  scope variable that ColdFusion uses to set application properties and describes their uses.

Variable

Default

Description

applicationTimeout

Administrator value

Life span , as a real number of days, of the application, including all Application scope variables. Use the createTimeSpan function to generate this variable.

clientManagement

False

Whether the application supports Client scope variables.

clientStorage

Administrator value

Where Client variables are stored; can be  cookie , registry, or the name of a data source.

loginStorage

Cookie

Whether to store login information in the Cookie scope or the Session scope.

scriptProtect

Administrator Value

Whether to protect variables from cross-site scripting attacks.

sessionManagement

False

Whether the application supports Session scope variables.

sessionTimeout

Administrator Value

Life span , as a real number of days, of the user session, including all Session variables. Use the createTimeSpan function to generate this variable.

setClientCookies

True

Whether to send CFID and CFTOKEN cookies to the client browser.

setDomainCookies

False

Whether to use domain cookies for the CFID and CFTOKEN values used for client identification, and for Client scope variables stored using cookies. If False, ColdFusion uses host-specific cookies. Set to True for applications running on clusters.

The following example code from the top of an Application.cfc sets the application name and properties:

<cfcomponent>
<cfset This.name = "TestApplication">
<cfset This.clientmanagement="True">
<cfset This.loginstorage="Session">
<cfset This.sessionmanagement="True">
<cfset This.sessiontimeout="#createtimespan(0,0,10,0)#">
<cfset This.applicationtimeout="#createtimespan(5,0,0,0)#">

For more information on these settings, see cfapplication in the CFML Reference.

Setting page processing options

The  cfsetting  tag lets you specify the following page processing attributes to apply to all pages in your application:

Attribute

Use

showDebugOutput

Specifies whether to show debugging output. This setting cannot enable debugging if it is disabled in the ColdFusion Administrator. However, this option ensures that debugging output is not displayed, even if the Administrator enables it.

requestTimeout

Specifies the page request time-out. If ColdFusion cannot complete processing a page within the time-out period, it generates an error. This setting overrides the setting in the ColdFusion Administrator. Use this setting to increase the page time-out if your application or page frequently accesses external resources that are slow, such as external LDAP servers or web services providers.

enableCFOutputOnly

Disables output of text that is not included inside  cfoutput  tags. This setting helps ensure that extraneous text in your ColdFusion pages does not get displayed.

Often, you use the cfsetting tag on individual pages, but you can also use it in your Application.cfc file. For example, using it in multi-application environment to override the ColdFusion Administrator settings in one application.
You can place an application-wide cfsetting tag in the component initialization code, normally following the This scope application property settings, as the following example shows:

<cfscript>
This.name="MyAppl";
This.clientmanagement="True";
This.loginstorage="Session" ;
This.sessionmanagement="True" ;
This.sessiontimeout=CreateTimeSpan(0,0,1,0);
</cfscript>
<cfsetting showdebugoutput="No" enablecfoutputonly="No">

The cfsetting tag in this example affects all pages in an application. You can override the application-wide settings in the event methods, such as onRequestStart, or on individual ColdFusion pages.

Using application event handlers

The following table describes the application event CFC methods that you can implement, including when they are triggered.

Method

When run

onApplicationStart

The application first starts: when the first request for a page is processed or the first CFC method is invoked by an event gateway instance, Flash Remoting request, or a web service invocation. This method is useful for setting application-wide (Application scope) variables, such as the names of data sources.

onApplicationEnd

The application ends: when the application times out or the server shuts down.

onSessionStart

A new session is created as a result of a request that is not in an existing session, including ColdFusion event gateway sessions. The application must enable sessions for this event to happen.

onSessionEnd

A session time-out setting is reached. This event is not triggered when the application ends or the server shuts down.

onRequestStart

ColdFusion receives any of the following: a request, an HTTP request (for example, from a browser), a message to an event gateway, a SOAP request, or a Flash Remoting request.

onRequest

The onRequestStart event has completed. This method acts as a filter for the requested page content.

onRequestEnd

All pages and CFCs in the request have been processed: equivalent to the OnRequestEnd.cfm page.

onMissingTemplate

When ColdFusion receives a request for a nonexistent page.

onError

When an exception occurs that is not caught by a try/catch block.

When ColdFusion receives a request, it instantiates the Application CFC and runs the Application.cfc code in the following order:

  • CFC initialization code at the top of the file
  • onApplicationStart, if not run before for this application
  • onSessionStart, if not run before for this session
  • onRequestStart
  • onRequest, or the requested page if there is no onRequest method
  • onRequestEnd
    The following methods are triggered by specific events:
  • onApplicationEnd
  • onSessionEnd
  • onMissingTemplate
  • onError
    The onApplicationEnd and onSessionEnd methods do not execute in the context of a page request, so they cannot access request variables or display information to the user. The onMissingTemplate method is triggered when a URL specifies a CFML page that does not exist. The OnError method does not always execute in the context of a request; use its Event argument to determine the context.

Managing the application with Application.cfc

Use the onApplicationStart and onApplicationEnd methods to configure and manage the application; that is, to control resources that are used by multiple pages and requests and must be consistently available to all code in your application. Such resources include data sources, application counters such as page hit variables, or style information for all pages.
The onApplicationStart method executes when ColdFusion gets the first request for a page in the application after the server starts. The onApplicationEnd method executes when the application server shuts down or if the application is inactive for the application time-out period.
The following are some of the ways you use these methods. For more information, see entries for onApplicationStart and onApplicationEnd in the CFML Reference.

Defining application utility functions

Functions that you define in Application.cfc and do not place in a shared scope are, by default, available only to other methods in the CFC. 
If your Application.cfc implements the onRequest method, any utility functions that you define in Application.cfc are also directly available in to the target page, because Application.cfc and the target page share the Variables scope.
If your application requires utility functions that are used by multiple pages, not just by the methods in Application.cfc, and you do not use an onRequest method, Adobe recommends that you place them in a separate CFC and access them by running that CFC. As with other ColdFusion pages, Application.cfc can access any CFC in a directory path that is configured on the ColdFusion Administrator Mappings page. Therefore, use this technique to share utility functions across applications.
If your Application.cfc defines utility functions that you want available on request pages and does not use an onRequest method, explicitly place the functions in a ColdFusion scope, such as the Request scope, as the following code shows:

<!--- Function definition goes here. --->
</cffunction>

<cffunction name="OnRequestStart">
<!--- OnRequestStart body goes here --->
<cfset Request.theFunctionName=This.theFunctionName>
</cffunction>

On the request page, you would include the following code:

<cfset myVar=Request.theFunctionName(Argument1...)>

Functions that you define in this manner share the This scope and Variables scope with the Application.cfc file for the request.

Setting application default variables and constants in onApplicationStart

You can set default variables and application-level constants in Application.cfc. For example, you can do the following:

  • Specify a data source and ensure that it is available
  • Specify domain name
  • Set styles, such as fonts or colors
  • Set other application-level variables
    You do not have to lock Application scope variables when you set them in the Application.cfc onApplicationStart method.
    For details on implementing the onApplicationStart method, see onApplicationStart in the CFML Reference.

Using the onApplicationEnd method

Use the onApplicationEnd method for any clean-up activities that your application requires when it shuts down, such as saving data in memory to a database, or to log the application end. You cannot use this method to display data on a user page, because it is not associated with any request. The application ends, even if this method throws an exception. An application that is used often is unlikely to execute this method, except when the server is shut down. 
For details on implementing the onApplicationEnd method, see onApplicationEnd in the CFML Reference.

Managing sessions in Application.cfc

Use the onSessionStart and onSessionEnd methods to configure and manage user sessions; that is, to control resources that are used by multiple pages while a user is accessing your site from during a single browser session. The session begins when a user first requests a page in your  application,  and ends when the session times out. For more information on Session scope and Session variables, see Using Persistent Data and Locking.
Session resources include variables that store data that is needed throughout the session, such as account numbers, shopping cart contents, or CFCs that contain methods and data that are used by multiple pages in a session.

Note:

Do not include the cflogin tag or basic login processing in the onSessionStart method, as the code executes only at the start of the session; it cannot handle user logout, and cannot fully ensure security.

Using the onSessionStart method

This method is useful for initializing session data, such as user settings or shopping cart contents, or for tracking the number of active sessions. You do not need to lock the Session scope when you set session variables in this method.
For more information, see the onSessionStart entry in the CFML Reference.

Using the onSessionEnd method

Use this method for any clean-up activities when the session ends. (For information on ending sessions, see Ending a session in Configuring and using session variables.) For example, you can save session-related data, such as shopping cart contents or information about whether the user has not completed an order, in a database, or you can log the end of the session to a file. You cannot use this method to display data on a user  page,  because it is not associated with a request.

Note:

Sessions do not end, and the onSessionEnd method is not called when an application ends. For more information, see the  onSessionEnd  entry in the CFML Reference.

Managing requests in Application.cfc

ColdFusion provides three methods for managing requests: onRequestStart, onRequest, and onRequestEnd. ColdFusion processes requests, including these methods, as follows:

  1. ColdFusion always processes  onRequestStart  at the start of the request.

  2. If you implement an onRequest method, ColdFusion processes it; otherwise, it processes the requested page. If you implement an onRequest method, explicitly call the requested page in your onRequest method.

  3. ColdFusion always processes onRequestEnd at the end of the request.

    Note:

    When using cfabort, cflocation, or cfcontent tags, the OnAbort method is invoked instead of OnRequestEnd.

You can use each of the Application.cfc request methods to manage requests as follows:

Using the onRequestStart method

This method runs at the beginning of the request. It is useful for user authorization (login handling), and for request-specific variable initialization, such as gathering performance statistics.
If you use the onRequestStart method and do not use the onRequest method, ColdFusion automatically processes the request when it finishes processing the onRequestStart code.

Note:

If you do not include an onRequest method in Application.cfm file, the onRequestStart method does not share a Variables scope with the requested page, but it does share Request scope variables.

For more information, see the entry for onRequestStart in the CFML Reference

User authentication

When an application requires a user to log in, include the authentication code, including the  cflogin  tag or code that calls this tag, in the onRequestStart method. Doing so ensures that the user is authenticated at the start of each request. For detailed information on security and creating logins, see Securing Applications For an example that uses authentication code generated by the Adobe Dreamweaver CF Login Wizard, see onRequestStart in the CFML Reference.

Using the onRequest method

The onRequest method differs from the onRequestStart method in one major way: the onRequest method intercepts the user's request. This difference has two implications:

  • ColdFusion does not process the request unless you explicitly call it, for example, by using a  cfinclude  tag. This behavior lets you use the onRequest method to filter requested page content or to implement a switch that determines the pages or page contents to be displayed.
  • When you use  cfinclude  to process  request , the CFC instance shares the Variables scope with the requested page. As a result, any method in the CFC that executes can set the page's Variables scope variables, and the onRequestEnd method can access any Variable scope values that the included page has set or changed. Therefore, for example, the onRequestStart or onRequest method set variables that are used on the page.
    To use this method as a filter, place the  cfinclude  tag inside a  cfsavecontent  tag, as the following example shows:
<cfargument name = "targetPage" type="String" required=true/>
<cfsavecontent variable="content">
<cfinclude template=#Arguments.targetPage#>
</cfsavecontent>
<cfoutput>
#replace(content, "report", "MyCompany Quarterly Report", "all")#
</cfoutput>
</cffunction>

For more information, see the entry for onRequest in the CFML Reference

Using the onRequestEnd method

You use the onRequestEnd method for code that should run at the end of each request. (In ColdFusion versions through ColdFusion MX 6.1, you would use the OnRequestEnd.cfm page for such code). Typical uses include displaying dynamic footer pages. For an example, see onSessionEnd in the CFML Reference.

Note:

If you do not include an onRequest method in Application.cfm file, the onRequestEnd method does not share a Variables scope with the requested page, but it does share Request scope variables.

For more information, see the entry for onRequestEnd in the CFML Reference.

Handling errors in Application.cfc

The following sections briefly describe how you to handle errors in Application.cfc. For more information on error pages and error handling, see Handling Errors For details on implementing the onError method, see onError in the CFML Reference.

Application.cfc error handling techniques

Application.cfc handles errors in any combination of the following ways:

  • Use try/catch error handling in the event methods, such as onApplicationStart or onRequestStart, to handle exceptions that happen in the event methods.
  • Implement the onError method. This method receives all exceptions that are not directly handled by try/catch handlers in CFML code. The method can use the  cfthrow  tag to pass any errors it does not handle to ColdFusion for handling.{{}}

  • Use  cferror  tags in the application initialization code following the  cfcomponent  tag, typically following the code that sets the application's This scope variables . These tags specify error processing if you do not implement an onError  method, or if the onErrormethod throws an error. You could implement an application-specific validation error handler, for example, by placing the following tag in the CFC initialization code:

<cferror type="VALIDATION" template="validationerrorhandler.cfm">
  • The ColdFusion default error mechanisms handle any errors that are not handled by the preceding techniques. These mechanisms include the site-wide error handler that you specify in the ColdFusion Administrator and the built-in default error pages.
    These techniques let you include application-specific information, such as contact information or application or version identifiers, in the error message, and let you display all error messages in the application in a consistent manner. You use Application.cfc to develop sophisticated application-wide error-handling techniques, including error-handling methods that provide specific messages, or use structured error-handling techniques.
Note:

The onError method catches errors that occur in the onSessionEnd and onApplicationEnd application event methods. It does not display messages to the user, however, because there is no request context. The onError function logs errors that occur when the session or application ends.

Handling server-side validation errors in the onError method

Server-side validation errors are actually ColdFusion exceptions; as a result, if your application uses an onError  method, this method gets the error and must handle it or pass it on to ColdFusion for handling.
To identify a server-side validation error, search the Arguments.Exception.StackTrace field for coldfusion .filter.FormValidationException. You can then handle the error directly in your onError routine, or throw the error so that either the ColdFusion default validation error page or a page specified by an  cferror  tag in your Application.cfc initialization code handles it.

Example: error Handling with the onError method

The following Application.cfc file has  an onError  method that handles errors as follows:

  • If the error is a server-side validation error, the onError method throws the error for handling by ColdFusion, which displays its standard validation error message.
  • For any other type of exception, the onError method displays the name of the event method in which the error occurred and dumps the exception information. In this example, because you generate errors on the CFM page only, and not in  a Application.cfc  method, the event name is always the empty string.
<cfset This.name = "BugTestApplication">
<cffunction name="onError">
<!--- The onError method gets two arguments:
An exception structure, which is identical to a cfcatch variable.
The name of the Application.cfc method, if any, in which the error
happened.
<cfargument name="Except" required=true/>
<cfargument type="String" name = "EventName" required=true/>
<!--- Log all errors in an application-specific log file. --->
<cflog file="#This.Name#" type="error" text="Event Name: #Eventname#" >
<cflog file="#This.Name#" type="error" text="Message: #except.message#">
<!--- Throw validation errors to ColdFusion for handling. --->
<cfif Find("coldfusion.filter.FormValidationException",
Arguments.Except.StackTrace)>
<cfthrow object="#except#">
<cfelse>
<!--- You can replace this cfoutput tag with application-specific
error-handling code. --->
<cfoutput>
<p>Error Event: #EventName#</p>
<p>Error details:<br>
<cfdump var=#except#></p>
</cfoutput>
</cfif>
</cffunction>
</cfcomponent>

To test this example, place a CFML page with the following code in the same page as the Application.cfc file, and enter valid and invalid text in the text input field.

This box does Integer validation:
<cfinput name="intinput" type="Text" validate="integer" validateat="onServer"><br>
Check this box to throw an error on the action page:
<cfinput type="Checkbox" name="throwerror"><br>
<cfinput type="submit" name="submitit">
</cfform>
<cfif IsDefined("form.fieldnames")>
<cfif IsDefined("form.throwerror")>
<cfthrow type="ThrownError" message="This error was thrown from the bugTest action page.">
<cfelseif form.intinput NEQ "">
<h3>You entered the following valid data in the field</h3>
<cfoutput>#form.intinput#</cfoutput>
</cfif>
</cfif>
Note:

For more information on server-side validation errors, see Validating data.

Example: a complete Application.cfc

The following example is a simplified Application.cfc file that illustrates the basic use of all application event handlers:

<cfset This.name = "TestApplication">
<cfset This.Sessionmanagement=true>
<cfset This.Sessiontimeout="#createtimespan(0,0,10,0)#">
<cfset This.applicationtimeout="#createtimespan(5,0,0,0)#">

<cffunction name="onApplicationStart">
<cftry>
<!--- Test whether the DB that this application uses is accessible
by selecting some data. --->
<cfquery name="testDB" dataSource="cfdocexamples" maxrows="2">
SELECT Emp_ID FROM employee
</cfquery>
<!--- If we get database error, report it to the user, log the error
information, and do not start the application. --->
<cfcatch type="database">
<cfoutput>
This application encountered an error.<br>
Please contact support.
</cfoutput>
<cflog file="#This.Name#" type="error"
text="cfdocexamples DB not available. message: #cfcatch.message#
Detail: #cfcatch.detail# Native Error: #cfcatch.NativeErrorCode#">
<cfreturn False>
</cfcatch>
</cftry>
<cflog file="#This.Name#" type="Information" text="Application Started">
<!--- You do not have to lock code in the onApplicationStart method that sets Application scope variables. --->
<cfscript>
Application.availableResources=0;
Application.counter1=1;
Application.sessions=0;
</cfscript>
<!--- You do not need to return True if you don't set the cffunction returntype attribute. --->
</cffunction>

<cffunction name="onApplicationEnd">
<cfargument name="ApplicationScope" required=true/>
<cflog file="#This.Name#" type="Information"
text="Application #ApplicationScope.applicationname# Ended">
</cffunction>


<cffunction name="onRequestStart">
<!--- Authentication code, generated by the Dreamweaver Login Wizard,
makes sure that a user is logged in, and if not displays a login page. --->
<cfinclude template="mm_wizard_application_include.cfm">
<!--- If it's time for maintenance, tell users to come back later. --->
<cfscript>
if ((Hour(now()) gt 1) and (Hour(now()) lt 3)) {
WriteOutput("The system is undergoing periodic maintenance.
Please return after 3:00 AM Eastern time.");
return false;
} else {
this.start=now();
}
</cfscript>
</cffunction>

<cffunction name="onRequest">
<cfargument name = "targetPage" type="String" required=true/>
<cfsavecontent variable="content">
<cfinclude template=#Arguments.targetPage#>
</cfsavecontent>
<!--- This is a minimal example of an onRequest filter. --->
<cfoutput>
#replace(content, "report", "MyCompany Quarterly Report", "all")#
</cfoutput>
</cffunction>

<!--- Display a different footer for logged in users than for guest users or 
users who have not logged in. --->

<cffunction name="onRequestEnd">
<cfargument type="String" name = "targetTemplate" required=true/>
<cfset theAuthuser=getauthuser()>
<cfif ((theAuthUser EQ "guest") OR (theAuthUser EQ ""))>
<cfinclude template="noauthuserfooter.cfm">
<cfelse>
<cfinclude template="authuserfooter.cfm">
</cfif>
</cffunction>

<cffunction name="onSessionStart">
<cfscript>
Session.started = now();
Session.shoppingCart = StructNew();
Session.shoppingCart.items =0;
</cfscript>
<cflock timeout="5" throwontimeout="No" type="EXCLUSIVE" scope="SESSION">
<cfset Application.sessions = Application.sessions + 1>
</cflock>
<cflog file="#This.Name#" type="Information" text="Session:
#Session.sessionid# started">
</cffunction>

<cffunction name="onSessionEnd">
<cfargument name = "SessionScope" required=true/>
<cflog file="#This.Name#" type="Information" text="Session:
#arguments.SessionScope.sessionid# ended">
</cffunction>

<cffunction name="onError">
<cfargument name="Exception" required=true/>
<cfargument type="String" name = "EventName" required=true/>
<!--- Log all errors. --->
<cflog file="#This.Name#" type="error" text="Event Name: #Eventname#">
<cflog file="#This.Name#" type="error" text="Message: #exception.message#">
<!--- Some exceptions, including server-side validation errors, do not
generate a rootcause structure. --->
<cfif isdefined("exception.rootcause")>
<cflog file="#This.Name#" type="error"
text="Root Cause Message: #exception.rootcause.message#">
</cfif>
<!--- Display an error message if there is a page context. --->
<cfif NOT (Arguments.EventName IS onSessionEnd) OR
(Arguments.EventName IS onApplicationEnd)>
<cfoutput>
<h2>An unexpected error occurred.</h2>
<p>Please provide the following information to technical support:</p>
<p>Error Event: #EventName#</p>
<p>Error details:<br>
<cfdump var=#exception#></p>
</cfoutput>
</cfif>
</cffunction>

</cfcomponent>

Get help faster and easier

New user?

Quick links

View all your plans Manage your plans
View quick links
Hide quick links

Legal Notices    |    Online Privacy Policy