Variable
Last updated on
Jan 13, 2022
|
Also applies to ColdFusion
Use session variables when you need the variables for a single site visit or set of requests within a short period of time (such as hours). For example, 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, such as over days, weeks, or months.)
Note:
Place code that uses session variables inside cflock tags in circumstances that could result in race conditions from multiple accesses to the same variable. 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 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 in this page.
ColdFusion and J2EE session management
The ColdFusion server can use either of the following types of session management:
- ColdFusion session management
- J2EE session management
ColdFusion session management uses the same client identification method as ColdFusion client management.
J2EE session management provides the following advantages over ColdFusion session management:
- J2EE session management uses a session-specific session identifier, jsessionid , which is created afresh at the start of each session.
- You can share session variables between ColdFusion pages and JSP pages or Java servlets that you call from the ColdFusion pages.
- The Session scope is serializable (convertible into a sequence of bytes that can later be fully restored into the original object). With ColdFusion session management, the Session scope is not serializable. Only serializable scopes can be shared across servers.
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.
- You want to support clustered sessions; for example, to support session failover among servers.
Configuring and enabling session variables
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.
Selecting and enabling session variables in ColdFusion Administrator
To use session variables, they must be enabled on the ColdFusion 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. Application code can override this value. The default value for this time-out is 20 mins.
- Specify a maximum session time-out. Application code 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
Enable session variables in the initialization code of your Application.cfc file or in the cfapplication tag in your Application.cfm file.
Do the following in the Application.cfc initialization code, below the cfcomponent tag, to enable session variables:
- Set This.sessionManagement="Yes".
- Set This.name to specify the name of the application.
- Optionally, set This.sessionTimeout 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.
Do the following in the Application.cfm file to enable session variables:
- Set sessionManagement="Yes"
- Use the name attribute to specify the name of the application.
- 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 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.
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 in Managing the client state. The following table describes the built-in session variables.
|
|
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: A combination of the CFID and CFToken cookies and the J2EE session ID, in the form {{CFID=}}IDNum{{&CFTOKEN=}}tokenNum{{&jsessionid=}}SessionID. |
|
Session.SessionID |
A unique identifier for the session.ColdFusion session management: a combination of 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>
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>
If you set session variables on a CFML template that uses the cflocation tag, ColdFusion might not set the variables. For more information, see TechNote at www.adobe.com/go/tn_18171. |
Accessing and changing session variables
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>
Ending a session
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.
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.