Defining the application and its event handlers in Application.cfc

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.

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.

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.

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

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:

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

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:

<cffunction name="theFunctionName" returntype="theReturnType"> 
    <!--- 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.

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.

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.

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.

Use this method for any clean-up activities when the session ends. (For information on ending sessions, see Ending a session.) 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.

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.

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

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.

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:

<cffunction name="onRequest"> 
    <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

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.

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

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 onError method 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.

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.

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.

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

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