Application Variable Timeouts

By default, application variables are kept on the server almost indefinitely. They die only if two whole days pass without any visits to any of the application's pages. After two days of inactivity, ColdFusion considers the APPLICATION scope to have expired, and the onApplicationEnd method of the Application.cfc file is called, if it exists. Whether or not this method exists, all associated application variables are flushed from its memory.

If one of your applications uses a large number of application variables but is used very rarely, you could consider decreasing the amount of time that the APPLICATION scope takes to expire. Doing so would let ColdFusion reuse the memory taken up by the application variables. In practice, there might be few situations in which this flexibility is useful, but you should still know what your options are if you want to think about ways to tweak the way your applications behave.

Two ways are available to adjust the application timeout period from its two-day default value. You can use the ColdFusion Administrator or the applicationTimeout value of the THIS scope in the Application.cfc file.

Adjusting Timeouts Using APPLICATIONTIMEOUT

As shown in Table 19.4, the Application.CFC THIS scope takes an optional applicationTimeout value. You can use this to explicitly specify how long an unused APPLICATION scope will remain in memory before it expires.

Table 19.4. THIS Scope Values Relevant to Application Variables

ATTRIBUTE	DESCRIPTION
name	A name for your application. The name can be anything you want, up to 64 characters long. ColdFusion uses this name internally to store and look up your application variables for you. It should be unique per application.
applicationTimeout	Optional. How long you want your application variables to live in the server's memory. If you don't provide this value, it defaults to whatever is set up in the Memory Variables page of the ColdFusion Administrator. See the section "Application Variable Timeouts," later in this chapter. The maximum value can't be higher than the maximum value specified in the Memory Variables page of the ColdFusion Administrator.

The applicationTimeout value expects a ColdFusion time span value, which is a special type of numeric information used to describe a period of time in terms of days, hours, minutes, and seconds. All this means is that you must specify the application timeout using the createTimeSpan() function, which takes four numeric arguments to represent the desired number of days, hours, minutes, and seconds, respectively (for more information about the createTimeSpan() function, see Appendix C).

For instance, to specify that an application should time out after two hours of inactivity, you would use code such as this:

 <cfset THIS.applicationTimeout="#CreateTimeSpan(0,2,0,0)#"> 

NOTE

If you don't specify an applicationTimeout attribute, the Default Timeout value in the Variables page of the ColdFusion Administrator is used. See the next section, "Adjusting Timeouts Using the ColdFusion Administrator," for details.

NOTE

If you specify an applicationTimeout that exceeds the Maximum Timeout value in the Variables page of the ColdFusion Administrator, the Maximum Timeout in the Administrator is used instead. See the next section, "Adjusting Timeouts Using the ColdFusion Administrator," for details.

Don't forget that you can now execute code when the application times out. Listing 19.6 demonstrated a simple use of the onApplicationEnd method.

Adjusting Timeouts Using the ColdFusion Administrator

To adjust the amount of time that each application's APPLICATION scope should live before it expires, follow these steps:

1.	Navigate to the Memory Variables page of the ColdFusion Administrator.
2.	Under Default Timeout, fill in the days, hours, minutes, and seconds fields for application variables, as shown in Figure 19.6.
3.	If you want, you also can adjust the Maximum Timeout for application variables here. If any developers attempt to use a longer timeout with the applicationTimeout value in the Application.cfc THIS scope, this value will be used instead (no error message is displayed).
4.	Click Submit Changes.

Using onRequest()

So far we have seen examples of how you can run code before and after a page request, as well as during the startup and end of the application. Another way to modify the behavior of your pages is with the onRequest method. This method is executed after the onRequestStart method, and before the onRequestEnd method. It takes one argument, the template currently being executed. If you don't actually include the template, using <cfinclude>, then your page won't show up.

Using this method has some serious drawbacks. The mere existence of this method won't allow any Flash Remoting or Web Services calls. The method also tends to "leak" variables into the template itself. If all of this sounds confusing, don't worry. Typically you won't need to use the onRequest method. If you simply want to wrap a page with a header and footer, for example, you can just use onRequestStart and onRequestEnd.

With that in mind, let's look at a simple example of where the onRequest method can be helpful. You may have seen some Web sites that have "Print" versions of their articles. These are versions of the article that normally have much reduced HTML. This is easy to build to do with advanced style sheets, or dynamically with ColdFusion, but what if you have old content, or pages, that weren't built to support a Print version? We can use the onRequest method to handle this situation. Listing 19.6 shows a modified version of our latest Application.cfc file. Since we are only modifying two methods and adding the onRequest method, we only list them below. The CD will have the entire file.

Listing 19.16. Application8.cfcUsing onRequest

 <cffunction name="onRequestStart" returnType="boolean" output="true">   <!--- Any variables set here can be used by all our pages --->   <cfset request.dataSource = "ows">   <cfset request.companyName = "Orange Whip Studios">   <!--- Display our Site Header at top of every page --->   <cfif not isDefined("URL.print")>     <cfinclude template="SiteHeader.cfm">   </cfif>   <cfreturn true> </cffunction> <cffunction name="onRequestEnd" returnType="void" output="true">   <!--- Display our Site Footer at bottom of every page --->   <cfif not isDefined("URL.print")>     <cfinclude template="SiteFooter.cfm">   </cfif> </cffunction> <cffunction name="onRequest" returnType="void" outout="true">   <cfargument name="targetPage" type="string" required="true">   <cfset var content = "">   <cfif not isDefined("URL.print")>     <cfinclude template="#arguments.targetPage#">   <cfelse>     <!--- Show the Print version --->     <!--- First we let the file run and save the result --->     <cfsavecontent variable="content">       <cfinclude template="#arguments.targetPage#">     </cfsavecontent>     <!--- Remove HTML --->     <cfset content = reReplace(content,"<.*?>","","all")>     <cfoutput><pre>#content#</pre></cfoutput>   </cfif> </cffunction> 

Let's start with the onRequestStart and onRequestEnd methods. Both of these methods are the same as in the earlier version, except now they check for the existence of a URL variable print. If the variable exists, these methods don't include the header and footer. Now let's look at the onRequest method. This method takes one argument, the filename of the template being executed. You must include this template or it will never show up. Once again we check for the existence of the URL variable print. If it doesn't exist, we simply include the file.

The interesting part comes up when the variable does exist. First, we <cfinclude> the template, but wrap it with the <cfsavecontent> tag. This runs the template and saves all the content into a variable, in this case, content. Next, we use a regular expression (discussed in the Advanced Macromedia Cold Fusion MX 7 Web Application Development book) to remove the HTML. Don't worry too much about this codejust know that it will remove all the HTML and leave the text behind. Lastly, we output the result wrapped in <pre> tags. The net result is that HTML that looks like so:

 <h1>Welcome to our Site</h1> Thanks for <b>visiting!</b>. 

Will be rendered like so:

 Welcome to our Site Thanks for visiting! 

Now a Print version of your site can be generated by just adding a "print=1" to the current URL.

Figure 19.5. You can adjust when an application expires using the Variables page of the ColdFusion Administrator.