cfcache

Description

Speeds up page rendering when dynamic content does not have to be retrieved each time a user accesses the page. To accomplish this, cfcache creates temporary files that contain the static HTML returned from a ColdFusion page.

You can use cfcache for simple URLs and URLs that contain URL parameters.

Syntax


<cfcache action = "cache" or "flush" or 

    "clientCache" or "optimal"

  username = "username"

  password = "password"

  protocol = "protocol_name"

  timeout = "#DateAdd(datepart, number, date)#"

  directory = "directory_name_for_map_file"

  cacheDirectory = "directory_name_for_cached_pages"

  expireURL = "wildcarded_URL_reference"

  port = "port_number">

Attributes

Attribute

Description

action
Optional. One of the following:

cache    Specifies server-side caching. The default is cache.

flush    Refresh the cached page. If you specify flush, you can also specify the directory and expireURL attributes.

clientCache    Specifies browser caching.

optimal    Specifies optimal caching through a combination of server-side and browser caching.

For more information, see the Usage section.

username
Optional. When required for basic authentication, a valid username.

password
Optional. When required for basic authentication, a valid password.

protocol
Optional. Specifies the protocol used to create pages from cache. Either http:// or https://. The default is http://.

timeout
Optional. DateTime that specifies the oldest acceptable cached page. If the cached page is older than the specified datetime, ColdFusion refreshes the page. By default, ColdFusion uses all cached pages. For example, if you want a cached file to be no older than 4 hours, code the following:
<cfcache timeout = "#DateAdd("h", "-4", Now() )#">

directory
Optional. Used with action = "flush". Specifies the fully qualified path of a directory that contains the cfcache.map to be used when action = "flush". The default is the directory of the current page.

cacheDirectory
Optional. Specifies the fully qualified path of the directory where pages are to be cached. The default is the directory of the current page.

expireURL
Optional. Used with action = "flush". ExpireURL takes a URL reference, including wildcards, that ColdFusion matches against all mappings in the cfcache.map file. The default is to flush all mappings. For example:
"foo.cfm" matches "foo.cfm"
"foo.cfm?*" matches "foo.cfm?x = 5" and "foo.cfm?x = 9"

port
Optional. The port number of the web server from which the page is requested. The port number defaults to 80. The port number is useful because the cfcache code calls cfhttp. If the port number is specified correctly in the internal call to cfhttp, the URL of each retrieved document is resolved to preserve links.

Attribute	Description
action	Optional. One of the following: `cache` Specifies server-side caching. The default is `cache`. `flush` Refresh the cached page. If you specify `flush`, you can also specify the `directory` and `expireURL` attributes. `clientCache` Specifies browser caching. `optimal` Specifies optimal caching through a combination of server-side and browser caching. For more information, see the Usage section.
username	Optional. When required for basic authentication, a valid username.
password	Optional. When required for basic authentication, a valid password.
protocol	Optional. Specifies the protocol used to create pages from cache. Either `http://` or `https://`. The default is `http://`.
timeout	Optional. DateTime that specifies the oldest acceptable cached page. If the cached page is older than the specified datetime, ColdFusion refreshes the page. By default, ColdFusion uses all cached pages. For example, if you want a cached file to be no older than 4 hours, code the following: <cfcache timeout = "#DateAdd("h", "-4", Now() )#">
directory	Optional. Used with `action = "flush"`. Specifies the fully qualified path of a directory that contains the `cfcache.map` to be used when `action = "flush"`. The default is the directory of the current page.
cacheDirectory	Optional. Specifies the fully qualified path of the directory where pages are to be cached. The default is the directory of the current page.
expireURL	Optional. Used with `action = "flush"`. `ExpireURL` takes a URL reference, including wildcards, that ColdFusion matches against all mappings in the `cfcache.map` file. The default is to flush all mappings. For example: `"foo.cfm"` matches `"foo.cfm"` `"foo.cfm?*"` matches `"foo.cfm?x` `=` `5"` and `"foo.cfm?x` `=` `9"`
port	Optional. The port number of the web server from which the page is requested. The port number defaults to 80. The port number is useful because the `cfcache` code calls `cfhttp`. If the port number is specified correctly in the internal call to `cfhttp`, the URL of each retrieved document is resolved to preserve links.

Usage

To enable the simplest form of caching, you just code cfcache at the top of a page.

With the action attribute, you can specify server-side caching, browser caching, or a combination of the two. The advantage of browser caching is that it takes no ColdFusion resources; the browser stores pages in its own cache, improving performance. The advantage of using a combination of the two forms of caching is that it optimizes performance; if the browser cache times out, the server can retrieve cached data from its own cache.

In addition to storing cached files, cfcache uses a mapping file, cfcache.map, to control caching. It uses a format similar to a Windows INI file. The mapping of a URL with parameters is stored as follows. Assume a directory c:\InetPub\wwwroot\dir1 that has a CFM file called foo.cfm, which can be invoked with or without URL parameters. The cfcache.map file entries for foo.cfm looks like this:

[foo.cfm]

Mapping = C:\InetPub\wwwroot\dir1\CFCBD.tmp

SourceTimeStamp = 08/31/1999 08:59:04 AM



[foo.cfm?x = 5]

Mapping = C:\InetPub\wwwroot\dir1\CFCBE.tmp

SourceTimeStamp = 08/31/1999 08:59:04 AM



[foo.cfm?x = 9]

Mapping = C:\InetPub\wwwroot\dir1\CFCBF.tmp

SourceTimeStamp = 08/31/1999 08:59:04 AM

The cfcache.map file in a directory stores mappings for that directory only. If the timestamp of the underlying page changes, ColdFusion updates the cache file for that URL. ColdFusion uses the SourceTimeStamp field to determine whether the currently cached file is up to date.

You can refresh the cache in the following ways:

timeout attribute ColdFusion tests the timestamp of the cached file against the timeout attribute If the cached file's timestamp is older than timeout, it deletes the old file and creates a new one. You can use fixed dates if necessary, but it's better to use relative dates. This works for seconds, hours, days, weeks, years, etc.
action = "flush" You use action = "flush" to force the clean up of cached files. It can take two attributes, directory and expireURL.
Manually Manually or programmatically (using cffile), delete .tmp files. This is not recommended.

Note the following regarding cfcache:

cfcache requires that ColdFusion Server "simultaneous requests" be greater than 1. When a cache file is generated, the requested page requires two connections to satisfy the request. When a cached file is found, only one request is required.
Debug settings have no effect on cfcache unless the application page explicitly turns it on. When generating a cached file, cfcache uses cfsetting showDebugOutput = "No".
ColdFusion does not cache pages that are dependent on anything other than URL parameters.
To use cfcache with the Secure Sockets Layer (SSL), specify
protocol = "http://".
If an application page returns an error, the error page is cached.

Example

<!--- This example produces as many cached files as there

     are possible URL parameter permutations. --->

<cfcache timeout = "#DateAdd("h", "-4", Now() )#">

<html>

<head>

<title>cfcache Example</title> 

</head>

<body>

<H1>cfcache Example</H1>



<H3>This is a test of some simple output</H3>

<cfparam name = "URL.x" default = "no URL parm passed" >

<cfoutput>The value of URL.x = # URL.x #</cfoutput>

</body>

</html>