cfcache

Search
ColdFusion User Guide
Applies to: ColdFusion

某些 Creative Cloud 应用程序、服务和功能在中国不可用。

Description

Stores a copy of a page on the server and/or client computer, to improve page rendering performance. To do this, the tag creates temporary files that contain the static HTML returned from a ColdFusion page.Use this tag if it is not necessary to get dynamic content each time a user accesses a page. You can use this tag for simple URLs and for URLs that contain URL parameters.

Category

Page processing tags

Syntax

<cfcache 
action = "action" 
dependsOn = "variable name list" 
directory = "directory path" 
expireURL = "wildcarded URL reference" 
id = "object identifier" 
idleTime = "decimal number of days" 
metadata = "variable name" 
name = "variable name" 
password = "password" 
port = "port number" 
protocol = "http://|https://" 
region = "region_name" 
stripWhiteSpace = "false|true" 
throwOnError = "false|true" 
timespan = "decimal number of days"> 
useCache = "true|false" 
usequerystring = "false|true" 
username = "username" 
value = "value"> 

The page fragment to be cached, if any. 

</cfcache>

Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

See also

cfflush, cfheader, cfhtmlhead, cfsetting, cfsilent, Cache functions

History

ColdFusion 10: Added the attribute region

ColdFusion 9:

  • Added support for the following features:
    • Caching in memory. Memory is now the default cache location.
    • Caching page fragments.
    • Caching specific objects, including the ability to put, get, and flush cached objects.
    • Setting cache dependencies.
    • Setting an idle timeout.
    • Getting metadata about cached objects.
    • The ability to strip white space from cached page fragments.
    • The ability to throw an exception if an error occurs when flushing a cached object.
  • Added get and put values of the action attribute. These values support caching of objects.
  • Added dependsOn, id, idleTime, key, metadata, name, stripWhiteSpace, throwOnError, useCache, useQueryString, and value attributes.

ColdFusion MX:

  • Deprecated the cachedirectory and timeout attributes. They might not work, and might cause an error, in later releases.
  • Added the timespan attribute.
  • Changed how pages are cached: the default action attribute value, cache, caches a page on the server and the client. (In earlier releases, this option cached a page only on the server.)
  • Changed the source of the protocol and port values: the default protocol and port values are now taken from the current page URL. (In earlier releases, they were "http" and "80", respectively.)
  • Changed how session state is handled when caching a page: this tag can cache pages that depend on session state, including pages that are secured with a ColdFusion login. (In earlier releases, the session state was cleared when caching the page, causing authentication to be lost.)
  • Changed how files are cached: this tag uses a hash() of the URL for the filename to cache a file. (In earlier releases, ColdFusion used the cfcache.map file.)

Attributes

Attribute

Actions

Req/Opt

Default

Description

action

All

Optional

serverCache
  • cache: server-side and client-side page caching.
  • clientcache: browser-side page caching only. To cache a personalized page, use this option.
  • flush: remove the current versions of cached pages, fragments, or an object from the cache. The cache is refreshed the next time a user accesses the item. For more information see Description.
  • get: get an object from the cache.
  • optimal: same as cache.
  • put: Add an object to the cache.
  • serverCache: server-side caching only.

dependsOn

cache, serverCache, optimal

Optional

 

A comma separated list of variables. If any of the variable values change, ColdFusion updates the cache. This attribute can take an expression that returns a list of variables.

directory

cache, serverCache, clientCache, optimal, flush, put

Optional

Cache in memory

Absolute path of cache directory.

expireURL

flush

Optional

Flush all cached pages

A URL reference. Can include wildcards, for example: "/view.cfm?id=". ColdFusion flushes, from the cache, pages that match the specified URL or pattern.

id

flush, get, put

See description

 

The identifier for a cached object. This attribute can also take a comma-separated list of identifiers.
This attribute is required for the any operation on an object. Therefore it is required for the get and put actions, and to flush an object. It is not required to flush a page.

idleTime

cache, serverCache, clientCache, optimal, flush, put

Optional

No idle timeout

Flushes the cached item if it is not accessed for the specified time span:

  • A decimal number of days, for example: ".25", for one-fourth day (6 hours); "1", for one day; "1.5", for one and one half days
  • A return value from the CreateTimeSpan function, for example, "#CreateTimeSpan(0, 6, 0, 0)#".

metadata

get

Optional

 

The name of a structure variable in which to put object metadata. The get operation returns the following data:

  • timespan: The time span during which the cached item is valid; the value of the timespan attribute for the cached item.
  • createdtime: The time when the cache was created
  • lasthit: The time when the cached item was most recently used.
  • hitnumber: Number of times the cached item has been used.
  • missnumber: Number of misses

name

get

Required

 

The name of the variable in which to put the retrieved object.

password

cache, serverCache, clientCache, optimal, flush

Optional

 

A password. Provide this if the page requires authentication at the web-server level.

port

cache, serverCache, clientCache, optimal, flush

Optional

The port for the current page

Port number of the web server from which the URL for the cached page is requested. In the internal call from cfcache to cfhttp, ColdFusion resolves each URL variable in the page; this ensures that links in the page remain functional.

protocol

cache, serverCache, clientCache, optimal, flush

Optional

The current page protocol

Protocol that is used to create URL from cache.

  • http://
  • https://

region

 

Optional

 

Name that you assign to a cache region

stripWhiteSpace

cache, serverCache, optimal

Optional

false

Specifies whether to strip any unnecessary white space characters from a cached page fragment. Does not have any effect on cached pages or objects.

throwOnError

flush with id attribute

Optional

false

A Boolean value specifying whether to throw an error if the flush action encounters an error. Otherwise the action does not generate an error if it fails. If this attribute is true you can handle the error in a cfcatch block, for example, if a specified id value is invalid.

timespan

cache, serverCache, clientCache, optimal, flush, put

Optional

See Description

The interval until the item is flushed from the cache.

  • A decimal number of days, for example: ".25", for one-fourth day (6 hours); "1", for one day; "1.5", for one and one half days
  • A return value from the CreateTimeSpan function, for example, "#CreateTimeSpan(0, 6, 0, 0)#".
    The default action is to flush the item when it is idle for the time specified by the idleTime attribute, or cfcache action = "flush" executes.

useCache

cache, serverCache, optimal,

Optional

true

Specifies whether to use caching for a page. This attribute can be useful during development. For example, you could use a function to predict when to use a cache, based on the application state.

useQueryString

 

Optional

false

If true, generates a template cache ID that includes the query string. This means that a new template cache is created whenever the query string changes.
If set to true, the attribute dependson considers the URL parameters defined in the query string as well to generate template caches. Also see the Usage section

username

cache, serverCache, clientCache, optimal, flush

Optional

 

A username. Provide this if the page being cached or flushed requires authentication at the web server level.

value

put

Required

 

The object to cache.

Usage

Page fragments: To cache a page fragment, put the fragment in the body of the tag, between the begin tag and the end tag. Do not use a tag body to cache full pages or objects.
flush: The flush action can have two formats: One uses the ExpireURL attribute to specify the page to flush, the other uses the id attribute to specify the object to flush. When you flush an object, ColdFusion ignores errors by default. If you specify a throwOnError attribute with a true value, the action throws the errors, and you can use a catch block to handle them. This is useful to determine if you use invalid cache ID values.
User-defined cache: To create user-defined cache,

  1. Add the following snippet to the ehcache.xml (in the _CF_root_lib):

<cache name="cf" 
maxElementsInMemory="10000" 
eternal="false" 
timeToIdleSeconds="86400" 
timeToLiveSeconds="86400" 
overflowToDisk="true" 
diskSpoolBufferSizeMB="30" 
maxElementsOnDisk="10000000" 
diskPersistent="true" 
diskExpiryThreadIntervalSeconds="3600" 
memoryStoreEvictionPolicy="LRU"/>

  1. To reference the user-defined cache, use the key attribute as follows:

<cfcache key="cf" timespan=#createtimespan(0,0,1,0)# > 
<cfoutput>#now()#</cfoutput> 
<cfcache>

By default, caching is memory-based and not disk-based. For each application, the default setting is 10000 object caches and 10000 template caches. It is important to note the limit imposed on the number of objects/templates that can be cached.
Diskoverflow for caching by default is false. To enable disk caching, set overflowTodisk as true in the ehcache.xml. To make the cached data available on server restart, set diskPersistent to true.
For further details of the properties in the ehcache.xml, refer to the documentation available at the following URL:http://ehcache.org/

ColdFusion 8 and earlier
The following remaining information for this tag also applies to previous releases.
Use this tag in pages whose content is not updated frequently. Taking this action can greatly improve the performance of your application.
The output of a cached page is stored in a file on the client browser and/or the ColdFusion server. Instead of regenerating and downloading the output of the page each time it is requested, ColdFusion uses the cached output. ColdFusion regenerates and downloads the page only when the cache is flushed, as specified by the timespan attribute, or by invoking cfcache action=flush.
To enable a simple form of caching, put a cfcache tag, specifying the timespan attribute, at the top of a page. Each time the specified time span passes, ColdFusion flushes (deletes) the copy of the page from the cache and caches a new copy for users to access.
You can specify client-side caching or a combination of client-side and server-side caching (the default), using the action attribute. The advantage of client-side caching is that it requires no ColdFusion resources; the browser stores pages in its own cache, improving performance. The advantage of combination caching is that it optimizes server performance; if the browser does not have a cache of the page, the server can get data from its own cache. (Adobe recommends that you use combination caching, and do not use server-side only caching.)
If a page contains personalized content, use the action = "clientcache" option to avoid the possibility of caching a personalized copy of a page for other users.
Debug settings have no effect on cfcache unless the application page enables debugging. When generating a cached file, cfcache uses cfsetting showDebugOutput = "no".
The cfcache tag evaluates each unique URL, including URL parameters, as a distinct page, for caching purposes. For example, the output of http://server/view.cfm?id=1 and the output of http://server/view.cfm?id=2 are cached separately.
The cfcache tag uses the cfhttp tag to get the contents of a page to cache. If there is an HTTP error accessing the page, the contents are not cached. If a ColdFusion error occurs, the error is cached.
For more information, see Caching ColdFusion pages that change infrequently in Optimizing ColdFusion applications in the Developing ColdFusion Applications.

Change in behavior
Till ColdFusion 9, the request query string was automatically used as part of the page identifier, so that pages with different query strings (URL parameters) are cached independent of each other. However, you must now specify the new optional attribute useQueryString with value set to true, to achieve the older behavior.

Example

<!---Cache this template for 30 seconds --->
<cfcache action="servercache" timeSpan="#createTimeSpan(0,0,0,30)#">
<!---Display the current time --->
<cfoutput>
	#timeFormat(now(),"hh:mm:ss tt")#
</cfoutput>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy