About persistent scope variables



ColdFusion provides four variable scopes, described in the following table, that let you maintain data that must be available to multiple applications or users or must last beyond the scope of the current request.

Variable scope

Description

Client

Contains variables that are available for a single client browser over multiple browser sessions in an application. For information about browser sessions, see, What is a session?.

Useful for client-specific information, such as client preferences, that you want to store for a significant period of time.

Data is stored as cookies, database entries, or Registry values. Client variables can time out after an extended period.

Although do not have to use the Client scope prefix in the variable name, code that uses the prefix is more efficient and easier to maintain.

Session

Contains variables that are available for a single client browser for a single browser session in an application.

Useful for client-specific information, such as shopping cart contents, that you want to persist while the client is visiting your application.

Data is stored in memory and times out after a period of inactivity or when the server shuts down.

ColdFusion Administrator lets you select between two kinds of session management, Standard ColdFusion Session management and J2EE session management. For information about types of session management, see ColdFusion and J2EE session management.

Use the Session scope prefix in the variable name.

Application

Contains variables that are available to all pages in an application for all clients.

Useful for application-specific information, such as contact information, that can vary over time and should be stored in a variable.

Data is stored in memory and times out after a period of inactivity or when the server shuts down.

Use the Application scope prefix in the variable name.

Server

Contains variables that are available to all applications in a server and all clients.

Useful for information that applies to all pages on the server, such as an aggregate page-hit counter.

Data is stored in memory. The variables do not time out, but you can delete variables you create, and all server variables are automatically deleted when the server stops running.

Use the Server scope prefix in the variable name.

The following sections provide information that is common to all or several of these variables. Later sections describe how to use the Client, Session, Application, and Server scopes in your applications, and provide detailed information about locking code.

ColdFusion persistent variables and ColdFusion structures

All persistent scopes are available as ColdFusion structures. As a result, you can use ColdFusion structure functions to access and manipulate Client, Session, Application, and Server scope contents. Information about using these functions in detail is not covered, but information about features or limitations that apply to specific scopes is provided.

Note: Although you can use the StructClear function to clear your data from the Server scope, the function does not delete the names of the variables, only their values, and it does not delete the contents of the Server.os and Server.ColdFusion structures. Using the StructClear function to clear the Session, or Application scope clears the entire scope, including the built-in variables. Using the StructClear function to clear the Client scope clears the variables from the server memory, but does not delete the stored copies of the variables.

ColdFusion persistent variable issues

Variables in the Session, Application, and Server scopes are kept in ColdFusion server memory. This storage method has several implications:

  • All variables in these scopes are lost if the server stops running.

  • Variables in these scopes are not shared by servers in a cluster.

  • To prevent race conditions and ensure data consistency, lock access to all code that changes variables in these scopes or reads variables in these scopes with values that can change.

Note: If you use J2EE session management and configure the J2EE server to retain session data between server restarts, ColdFusion retains session variables between server restarts.

Additionally, be careful when using client variables in a server cluster, where an application can run on multiple servers.

Locking memory variables

Because ColdFusion is a multi-threaded system in which multiple requests can share Session, Application, and Server scope variables, it is possible for two or more requests to try to access and modify data at the same time. ColdFusion runs in a J2EE environment, which prevents simultaneous data access, so multiple requests do not cause severe system errors. However, such requests can result in inconsistent data values, particularly when a page changes more than one variable.

To prevent data errors with session, application, and server variables, lock code that writes and reads data in these scopes. For more information, see Locking code with cflock.

Using variables in clustered systems

Because memory variables are stored in memory, they are not available to all servers in a cluster. As a result, you generally do not use Session, Application, or Server scope variables in clustered environment. However, use these scope variables in a clustered system in the following circumstances:

  • If the clustering system supports “sticky” sessions, in which the clustering system ensures that each user session remains on a single server. In this case, you can use session variables as you would on a single server.

  • You can use Application and Server scope variables in a cluster for write-once variables that are consistently set, for example, from a database.

To use client variables on a clustered system, store the variables as cookies or in a database that is available to all servers. If you use database storage, on one server only, select the Purge Data for Clients that Remain Unvisited option on the Client Variables, Add/Edit Client Store page in the Server Settings area in the ColdFusion Administrator.

For more information on using client and session variables in clustered systems, see Managing client identity information in a clustered environment.