Configuring and using session variables

A session refers to all the connections that a single client makes 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 mins. You can change the default time-out on the Memory Variables page in the Server Settings area in the ColdFusion Administrator.

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

For detailed information on ending sessions and deleting session variables, see Ending a session.

To use session variables, enable them in two places:

• ColdFusion Administrator

• The Application.cfc initialization code This.sessionManagement variable or the active cfapplication tag.

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

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 pages of the application. 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.

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.

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.

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>

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>

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

For example, to display the number of items in a user’s shopping cart, use the following code:

<cflock timeout=20 scope="Session" type="Exclusive"> 
    <cfoutput> 
        Your shopping cart has #Session.ShoppingCartItems# items. 
    </cfoutput> 
</cflock>

To 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>

The following rules apply to ending a session and deleting Session scope variables:

• If you use ColdFusion session management, ColdFusion automatically ends sessions and deletes all Session scope variables if the client is inactive for the session time-out period. The session does not end when the user closes the browser.

• If you use J2EE session management, ColdFusion ends the session and deletes all Session scope variables if the client is inactive for the session time-out period. However, the browser continues to send the same session ID, and ColdFusion reuses this ID for sessions with this browser instance, as long as the browser remains active.

• Logging a user out does not end the session or delete Session scope variables.

• In many cases, you can effectively end a session by clearing the Session scope, as shown in the following line. The following list, however, includes important limitations and alternatives:

  <cfset StructClear(Session)>

• Clearing the Session scope does not clear the session ID, and future requests from the browser continue to use the same session ID until the browser exits. It also does not log out the user, even if you use Session scope storage for login information. Always use the cflogout tag to log out users.

• If you use J2EE session management, you can invalidate the session, as follows:

  <cfset getPageContext().getSession().invalidate()>

  This line creates a pointer to the servlet page context and calls an internal method to reset the session. This clears all session information, including the session ID Session scope variables, and if you are using session login storage, the login information, for future request. However, the session information does remain available until the end of the current request. After you invalidate a session, attempts by the browser to access the application will generate an invalid session exception until the session times out.

  Note: You cannot destroy the session and create a session on the same request, as creating a new session involves sending session cookies back.

• If you do not use client cookies, the Session scope and login state is available to your application only as long as you pass the session’s CFID, CFTOKEN, and, for J2EE sessions, jsessionid values in the URL query string. After you stop using these values, however, the session data remains in memory until the session time-out period elapses.