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.

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

Add Comment

h2oman said on Jun 27, 2002 at 5:30 PM :

forcing session expiration on browser close.

use the following cookies to force sessions to expire a session @ browser close, instead of letting the cookies persist for the length of the session timeout.
<cfcookie name="CFID" value="#Session.CFID#">
<cfcookie name="CFTOKEN" value="#Session.CFTOKEN#">

okugawa said on Aug 22, 2002 at 8:58 AM :

Selecting and enabling session variables in ColdFusion MS Administrator
|
V
Selecting and enabling session variables in ColdFusion MX Administrator

bjoebox said on Oct 18, 2002 at 2:15 PM :

Can somebody improve this documentation? How do you force expire J2ee sessions?
Joe Eugene

pvagarwal said on Feb 21, 2003 at 2:59 PM :

The document says that once u enable J2EE session variables and check session.urltoken it will just give jsessionid, but i am getting both cfid, cftoken and the jsessionid... is this intentional... so if i have to maintain a session without cookies do i need to pass on all the variables above?

pvagarwal said on Feb 21, 2003 at 3:09 PM :

Article 23009 clarifies this issue -

http://www.macromedia.com/v1/Handlers/index.cfm?ID=23009&Method=Full

hlichtin said on May 28, 2003 at 11:23 AM :

As mentioned, the document is inaccurate on the contents of Session.URL token. A correct description is below. To use sessions without cookies, use the URLSessionFormat function as described in the ?Using client and session variables without cookies? section of Chapter 15 of Developing ColdFusion MX Applications with CFML. (If the client browser does not support cookies, the URLSessionFormat function automatically generates CFID and CTOKEN values and adds them to the returned URL string.)

------------------------
Here is a correct description:

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: A combination of the CFID and CFToken cookies and the J2EE session ID, in the form CFID=IDNum&CFTOKEN=tokenNum&jsessionid=SessionID. This is the only Session variable that includes CFID and CFToken values.

No screen name said on Oct 16, 2003 at 3:26 PM :

Can someone please help me this session end on browser close is frustrating. I have J2EE variable enabled in the Coldfusion Administrator.

In Application.cfm

<CFAPPLICATION NAME="TEST" SESSIONMANAGEMENT="YES" SETCLIENTCOOKIES="NO">

In Test.cfm

<CFLOCK SCOPE="SESSION" TYPE="exclusive" TIMEOUT="5">
<cfset SESSION.TEST.username = #form.username#>
<cfset SESSION.TEST.valid = #loginUserRet#>
</CFLOCK>

IF LOGOUT IS CLICKED
<cfset StructDelete(SESSION, "TEST")>

If the browser is closed and the user comes back to test.cfm the session is where they left it. I have tried numerous thing to kill the session after the browser is closed. Below is the list

Put the following in Application.cfm

<cfcookie name="CFID" value="#Session.CFID#">
<cfcookie name="CFTOKEN" value="#Session.CFTOKEN#">

Also

<cfif IsDefined("Cookie.CFID") AND IsDefined("Cookie.CFTOKEN")>
<cfset cfid_local = Cookie.CFID>
<cfset cftoken_local = Cookie.CFTOKEN>
<cfcookie name="CFID" value="#cfid_local#">
<cfcookie name="CFTOKEN" value="#cftoken_local#">
</cfif>

None of this is working any suggestions please email me at

christopher.williams@goodyear.com

Thanks

epicito said on Nov 19, 2003 at 8:34 AM :

Does someone know how to manage the "on session end" event in coldfusion?

Any suggestions on how to perform certain actions when a session ends. ("naturally" ends, of course)

jrunrandy said on Nov 19, 2003 at 8:42 AM :

Here are the two answers I know of:
1) Enable J2EE sessions write a Java listener that responds the session timeouts/ends. Here's how to do it in JRun: http://livedocs.macromedia.com/jrun/4/Programmers_Guide/servletlifecycleevents4.htm#1115816
2) Post your question to the online forums: http://webforums.macromedia.com/coldfusion/ I'm sure you're not the first person who has wanted to do this, and maybe someone else has a solution.

Kris DeLaney said on Jun 14, 2004 at 4:32 PM :

A programming researcher has determined that Session variables do not have to be locked! I have experimented with this exhaustively, and can also say that I can't find why they have to be locked. I only use J2EE Session Management because sessional and Session Variables are deleted upon browser close. Change default values on server so variable life does not exceed 1 hour. If you need longer life, set it in your code on an as-needed basis.

No screen name said on Jul 22, 2004 at 5:01 AM :

How do I save session data in response to a user button press? A number of books show using the href tag and sending the data as part of the url. I want to avoid sending data via the url, how do I update the session data based on the button and its associated values? Dee

WCrens01 said on Jul 21, 2005 at 11:05 AM :

To set session vars based on a button press, one way to do it would be to submit a form with the action = 'AnotherPage.cfm' on the button press. On the AnotherPage.cfm, set the session variable. If you want to return to the calling page after setting the session variable, CFInclude the calling page in the AnotherPage.cfm just after setting the session variable. Check for the session variable setting in the original program (which is now an include to AnotherPage.cfm). If if set, run the code that you want to execute after the session var is set. Otherwise, start at the beginning.

I hope that wasn't too confusing :-)

crennyw

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/sharedVars5.htm

Add Comment