Developing ColdFusion MX Applications with CFML
Using Persistent Data and Locking

Configuring and using session variables

Use session variables when you need the variables for a single site visit or set of requests. For example, you might use session variables to store a user's selections in a shopping cart application. (Use client variables if you need a variable in multiple visits.)

Caution:   To preserve data integrity, put code that uses session variables inside cflock tags. For information on using cflock tags see "Locking code with cflock".

What is a session?

A session refers to all the connections that a single client might make to a server in the course of viewing any pages associated with a given application. Sessions are specific to both the individual user and the application. As a result, every user of an application has a separate session and has access to a separate set of session variables.

This logical view of a session begins with the first connection to an application by a client and ends after that client's last connection. However, because of the stateless nature of the web, it is not always possible to define a precise point at which a session ends. A session should end when the user finishes using an application. In most cases, however, a web application has no way of knowing if a user has finished or is just lingering over a page.

Therefore, sessions always terminate after a time-out period of inactivity. If the user does not access a page of the application within this time-out period, ColdFusion interprets this as the end of the session and clears any variables associated with that session.

The default time-out for session variables is 20 minutes. You can change the default time-out on the Memory Variables page of ColdFusion Administrator Server tab.

You can also set the time-out period for session variables inside a specific application (thereby overruling the Administrator default setting) by using the cfapplication tag sessionTimeout attribute. However, you cannot use the cfapplication tag to set a time-out value that is greater than the maximum session time-out value set on the Administrator Memory Variables page.

Your application can also manually end a session, for example, when a user logs out.

ColdFusion and J2EE session management

The ColdFusion server can use either of the following types of session management:

• ColdFusion session management
• J2EE servlet session management

ColdFusion session management uses the same client identification method as ColdFusion client management. When you use ColdFusion session management, session variables are not available to JSP pages or Java servlets that you call from your ColdFusion pages.

J2EE session management uses a session-specific session identifier, jsessionid, which is created afresh at the start of each session. With J2EE session management, you can share session variables between ColdFusion pages and JSP pages or Java servlets that you call from the ColdFusion pages. Therefore, consider using J2EE session management in any of the following cases:

• You want to maximize session security, particularly if you also use client variables
• You want to share session variables between ColdFusion pages and JSP pages or servlets in a single application.
• You want to be able to manually terminate a session while maintaining the client identification cookie for use by the Client scope.

Configuring and enabling session variables

To use session variables, you must enable them in both of the following places:

• ColdFusion MX Administrator
• The active cfapplication tag

ColdFusion Administrator and the cfapplication tag also provide facilities for configuring session variable behavior, including the variable time-out.

Selecting and enabling session variables in ColdFusion MS Administrator

To use session variables, they must be enabled on the ColdFusion MX Administrator Memory Variables page. (They are enabled by default.) You can also use the Administrator Memory Variables page to do the following:

• Select to use ColdFusion session management (the default) or J2EE session management.
• Change the default session time-out. The cfapplication tag can override this value. The default value for this time-out is 20 minutes.
• Specify a maximum session time-out. The cfapplication tag cannot set a time-out greater than this value. The default value for this time-out is two days.

Enabling session variables in your application

You must also enable session variables in the cfapplication tag in your Application.cfm file. Do the following in the Application.cfm file to enable session variables:

• Set sessionManagement="Yes"
• Use the name attribute to specify the application's name.
• Optionally, use the sessionTimeout attribute to set an application-specific session time-out value. Use the CreateTimeSpan function to specify the number of days, hours, minutes, and seconds for the time-out.

The following sample code enables session management for the GetLeadApp application and sets the session variables to time out after a 45-minute period of inactivity:

<cfapplication name="GetLeadApp" 
sessionmanagement="Yes"
sessiontimeout=#CreateTimeSpan(0,0,45,0)#>

Storing session data in session variables

Session variables are designed to store session-level data. They are a convenient place to store information that all pages of your application might need during a user session, such as shopping cart contents or score counters.

Using session variables, an application can initialize itself with user-specific data the first time a user accesses one of the application's pages. This information can remain available while that user continues to use that application. For example, you can retrieve information about a specific user's preferences from a database once, the first time a user accesses any page of an application. This information remains available throughout that user's session, thereby avoiding the overhead of retrieving the preferences repeatedly.

Standard session variables

If you use ColdFusion session variables, the Session scope has four built-in, read-only variables that your application can use. If you use J2EE session management, the Session scope has two built-in variables. Generally, you use these variables in your ColdFusion pages only if your application supports browsers that do not allow cookies. For more information on supporting browsers that do not allow cookies, see "Using client and session variables without cookies". The following table describes the built-in session variables.

Variable	Description
Session.CFID	ColdFusion session management only: the client ID, normally stored on the client system as a cookie.
Session.CFToken	ColdFusion session management only: the client security token, normally stored on the client system as a cookie.
Session.URLToken	ColdFusion session management: a combination of the CFID and CFToken values in the form CFID=IDNum&CFTOKEN=tokenNum. Use this variable if the client does not support cookies and you must pass the CFID and CFToken variables from page to page. J2EE session management: the string jsessionid= followed by the J2EE session ID.
Session.SessionID	A unique identifier for the session. ColdFusion session management: the application name and CFID and CFToken values. J2EE session management: the jsessionid value.

Note:   ColdFusion lets you delete or change the values of the built-in session variables. As a general rule, avoid doing so.

If you enable client variables and ColdFusion session management, ColdFusion uses the same values for the Client and Session scope CFID, CFToken, and URLtoken variables. ColdFusion gets the values for these variables from the same source, the client's CFID and CFTOKEN cookies.

If you use J2EE session management, the Session scope does not include the Session.CFID or Session.CFToken variables, but does include the Session.URLToken and Session.SessionID variables. In this case, the Session.SessionID is the J2EE session ID and Session.URLToken consists of the string jsessionid= followed by the J2EE session ID.

Getting a list of session variables

Use the StructKeyList function to get a list of session variables, as follows:

<cflock timeout=20 scope="Session" type="Readonly">

  <cfoutput> #StructKeyList(Session)# </cfoutput>
</cflock>

Caution:   Always put code that accesses session variables inside cflock tags.

Creating and deleting session variables

Use a standard assignment statement to create a new session variable, as follows:

<cflock timeout=20 scope="Session" type="Exclusive">

  <cfset Session.ShoppingCartItems = 0>
</cflock>

Use the structdelete tag to delete a session variable; for example:

<cflock timeout=20 scope="Session" type="Exclusive">

  <cfset StructDelete(Session, "ShoppingCartItems")>
</cflock>

Note:   If you set session variables on a CFML template that uses the cflocation tag, ColdFusion might not set the variables. For more information, see Macromedia TechNote 22712 at http://www.macromedia.com/v1/Handlers/index.cfm?ID=22712&Method=Full.

Accessing and changing session variables

You use the same syntax to access a session variable as for other types of variables. However, you must lock any code that accesses or changes session variables.

For example, to display the number of items in a user's shopping cart, use favorite color that has been set for a specific user, for example, use the following code:

<cflock timeout=20 scope="Session" type="Exclusive">

  <cfoutput>
    Your shopping cart has #Session.ShoppingCartItems# items.
  </cfoutput>
</cflock>

To change increase the number of items in the shopping cart, use the following code:

<cflock timeout=20 scope="Session" type="Exclusive">

  <cfset Session.ShoppingCartItems = Session.ShoppingCartItems + 1>
</cflock>

Ending a session

If you use J2EE session management, the session and all session variables are deleted, when the user closes the browser.

If you use ColdFusion session management and do not explicitly terminate a session, for example when a user logs out, the session variables remain in ColdFusion server memory until the session time-out period elapses. If you store sensitive data, such as personally identifiable user information, in session variables, you should clear the data from the Session structure when the user logs out.

You can expire a session by using the cfapplication tag and setting the sessiontimeout attribute 0. The cfapplication tag must also reset all other attributes to the desired settings, as follows:

<cfapplication 

  name="MyApp" 
  clientmanagement="Yes"
  applicationtimeout="#CreateTimeSpan(0, 0, 0, 30)#" 
  sessionmanagement="Yes" 
  sessiontimeout=#CreateTimeSpan(0, 0, 0, 0)# > 

To save processing time, ColdFusion deletes expired session variables every 10 seconds. As a result, the session might continue to exist for up to 10 seconds after ColdFusion executes your code.

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments