9 Sessions and Cookies

This chapter explains how to use XML tags to manage sessions and cookies.

This chapter contains the following sections:

9.1 Understanding Sessions

Imagine a website containing two pages: main and water. Suppose a visitor sees main first and then moves on to water. HTTP is a stateless protocol. So, if a typical web server is managing this site, any knowledge gathered at main is lost when the visitor browses over to water. In other words, water cannot take advantage of any information that the visitor might have provided at main.

To get around this limitation, application servers detect when a visitor first enters a website. At that point, the application server starts a session for this visitor. In the preceding example, when the visitor requests the main page, the application server starts a session. The website designer can use main to gather information about the visitor and store that information in session variables. The information in session variables is available to all subsequent pages. So, for example, if Bob provides his age to main, and main's designer wrote the age to a session variable, then water could easily access Bob's age.

Session variables contain values available for the duration of the session. When the session ends, the application server destroys the session variables associated with that session. Each session variable consumes memory on the application server, so creating unnecessary session variables can hurt performance.

WebCenter Sites automatically creates some session variables; the website developer can optionally create others.

The application server can maintain sessions on a cluster.

9.2 Session Lifetime

A session begins when a visitor first hits your website. The session ends when any of the following happens:

  • The visitor terminates his browser.

  • The session has timed out. The cs.timeout property is used by WebCenter Sites to set the session timeout value in the application server. If this property is set to 300, then a user session becomes invalid in 300 seconds, or 5 minutes.

  • The system administrator stops the application server.

This section contains the following topics:

9.2.1 Session Variables Maintained by WebCenter Sites

Upon creating a session, WebCenter Sites automatically creates the following session variables:

Table 9-1 Session Variables

Session Variable What it Holds


The id of the visitor logged in.


The comma-separated list of all ACLs to which this visitor belongs. If the visitor has not explicitly logged in, the default ACL is Browser.


The username under which this visitor is logged in. If the visitor has not explicitly logged in, the default username is DefaultReader.


The name of the file containing WebCenter Sites properties.

9.2.2 Logging In and Logging Out

When a visitor first hits the site, WebCenter Sites creates a session and implicitly logs in the visitor as DefaultReader. During the session, if the visitor explicitly logs in, WebCenter Sites automatically updates the values of SessionVariables.currentUser, SessionVariables.currentAcl, and SessionVariables.username. Logging in does not affect the values of any other session variables. In other words, if your pages create session variables prior to a login, then those values are still valid after the login. When a visitor explicitly logs out, the WebCenter Sites-generated session variables automatically revert to the values they held prior to login. For example, consider the following sequence:

  1. A visitor first hits a page, so the value of SessionVariables.username is DefaultReader.

  2. The visitor logs in as marilyn, so the value of SessionVariables.username is marilyn.

  3. If marilyn logs out, the value of SessionVariables.username reverts to DefaultReader.

To trigger a logout, you call the <CATALOGMANAGER> tag with the ftcmd=logout modifier. When issuing this tag, you can optionally supply the killsession modifier, which destroys the current session. You can then create a new session by invoking the <CATALOGMANAGER> tag with the ftcmd=login modifier.

9.3 Sessions Example

Here's a simple session example, consisting of three very short elements:

Table 9-2 Sessions Example

Element What it Does


Asks visitors to pick their current mood.


Assigns the current mood to a session variable.


Evaluates the session variable.

This section contains the following topics:

9.3.1 FeelingsForm Element

The feelings form doesn't really involve sessions or variables; this element merely generates a form. The visitor's chosen mood is passed to the SetFeeling element:

<form action="ContentServer" method="post">
   <input type="hidden" name="pagename" 

 <P>How are you feeling right now?</P>
 <select name="Feeling" size="1">
    <option>Not so Good</option>

 <P><input type="submit" name="doit" value="Submit"/></P>

The resulting page looks like the following:

Description of g-feelingsform.png follows
Description of the illustration g-feelingsform.png

9.3.2 SetFeeling Element

Upon clicking the Submit button, the visitor is transported to SetFeeling. This element assigns the visitor's mood to a new session variable named CurrentFeeling.

<SETSSVAR NAME="CurrentFeeling" VALUE="Variables.Feeling"/>

<P>Welcome to our site.</P>

<P>Now proceed to  
<A href="ContentServer?pagename=CSGuide/Sessions/Meat">
some meaty content. 

The resulting page looks as follows:

Welcome to our site.
Now proceed to some meaty content.

If an element in this application asked the visitor to login, WebCenter Sites would have automatically set the username session variable to the visitor's login name. In that case, you could have personalized the welcome message in SetFeeling as follows:

<P>Welcome to our site, <CSVAR NAME="SessionVariables.username"/>

9.3.3 Meat Element

Upon clicking some meaty content, the visitor is transported to the Meat page. This page evaluates the session variable:

<IF COND="SessionVariables.CurrentFeeling=Good">
     <P>Sessions are happiness.</P>
     <P>Don't let sessions get you down.</P>

A visitor in a not so good mood sees:

Don't let sessions get you down.

Notice how CurrentFeeling was available to Meat. In fact, CurrentFeeling is available to any other elements in the session.

9.4 What Is a Cookie?

A cookie is a string that your application writes to the visitor's browser. A cookie stores information about visitors that lasts between sessions. The visitor's browser writes this string to a special cookie file on the visitor's disk. When that visitor returns to your website, the visitor's browser sends a copy of the cookie back to the web server that set it. Once a cookie has been created, it is available as a variable to elements on a page.

For example, your application might store the visitor's favorite sports team in a cookie. Then, when the visitor returns, your application could retrieve the cookie and use its information to display the team logo in a banner.

When cookies are no longer needed, you can delete them.

This section contains the following topics:

9.4.1 CookieServer

CookieServer is a servlet that sets cookies for you. You access CookieServer by creating cookies with the satellite.cookie tag.

9.4.2 Cookie Tags

WebCenter Sites offers two tags for managing cookies:

Table 9-3 Cookie Tags

Tag Use


Sets a cookie on the client's browser.


Deletes a cookie from the client's browser.

There is no special tag to obtain the value of a cookie. Instead, when a visitor returns to the website, WebCenter Sites loads the value of the cookie as a regular variable.

When creating a cookie (by calling satellite.cookie), you can specify the following attributes:

Table 9-4 Cookie Attributes

Attribute Value


Name of the cookie. This also serves as the name of the incoming variable containing the value of the cookie.

Important: Cookies in the WebCenter Sites page context are treated as variables. Therefore, when a cookie and an asset attribute share the same name, they are treated as the same variable.


Time in seconds after which the cookie no longer is sent to the web server.


Optionally set security on the cookie.


Restrict that the cookie only be sent on this URL


Restrict that the cookie only be sent to URLs in the specified domain.

Because they feel that cookies are a security threat, some visitors configure their browsers to reject cookies. If the information in the cookie is critical, your application must be prepared for this.

You must set or remove cookies before using any tags that stream content back to the visitor's browser. You must set or remove cookies even before the <HTML> tag.

9.5 Cookie Example

This example consists of several very short elements:

Table 9-5 Cookie Elements

Element What it Does


Determines whether a cookie is set. If cookie is set, call DisplayWelcome. If cookie is not set, call GetColorPreference.


Displays a form that asks visitor to pick her favorite color.


Creates a cookie on this visitor's browser. Then, redirects visitor to DisplayWelcome.


Displays a simple welcome message in the visitor's favorite color.

This section contains the following topics:

9.5.1 Start.xml

The Start.xml element determines whether the cookie has already been set. If the cookie has been set, WebCenter Sites stores its value inside a regular variable named Variables.ColorCookie. The code for Start.xml is as follows:

<IF COND="IsVariable.ColorCookie=true">
    <CALLELEMENT NAME="CSGuide/Sessions/DisplayWelcome"/>
    <CALLELEMENT NAME="CSGuide/Sessions/ColorForm"/>

9.5.2 ColorForm

The ColorForm.xml element displays some an HTML form to gather the visitor's favorite color. The code for ColorForm.xml is as follows:

<form action="ContentServer" method="post">
   <input type="hidden" name="pagename" value="CSGuide/Sessions/CreateCookie"/>

 <P>What is your favorite color?</P>
 <select name="FavoriteColor" size="1">

<P><input type="submit" name="doit" value="Submit"/></P>

9.5.3 CreateCookie

The CreateCookie.xml element sends a cookie named ColorCookie to the visitor's browser. If the visitor has disabled cookies, the browser ignores the request to set a cookie. If the visitor has enabled cookies (the default), the browser writes the cookie to this system's cookie file.

The following is the code for CreateCookie.xml:

<satellite.cookie NAME="ColorCookie" VALUE="Variables.FavoriteColor" 
TIMEOUT="31536000" SECURE="false"/> 

<CALLELEMENT NAME="CSGuide/Sessions/DisplayWelcome"/>

The preceding code sets the value of the cookie to the visitor's favorite color. This cookie lasts for one year (31,536,000 seconds).

9.5.4 DisplayWelcome

By the time DisplayWelcome is called, the cookie has been set. The following code uses the value of the cookie to display a welcome message in the visitor's favorite color.

<H1><font color="Variables.ColorCookie"
Displaying a Friendly Welcome.

9.5.5 Running the Cookie Example

To run the cookie example, use your browser to go to the following pagename:


The first time you run this example, all four elements execute. After the first time, only Start and DisplayWelcome execute.

9.6 Tips and Tricks

The following suggestions might be useful:

  • In a cluster, session state must be replicated across cluster members. In a cluster, try to keep session size to a minimum; don't store more than 2 Kilobytes of session data per client.

  • Determine reasonable session timeout values. Setting timeouts that are too large tie up system resources. Setting them too small forces visitors to log in with annoying frequency.

9.7 Satellite Server Session Tracking

websites that present personalized content to visitors must track sessions. WebCenter Sites and Satellite Server both track sessions. Both set cookies in the visitor's browser; thus, two cookies (rather than one) each independently track a session. This redundancy is useful if a Satellite Server goes down; when a Satellite Server goes down, the WebCenter Sites session is maintained.

Though Satellite Server will only serve session-specific pagelets back to the person who originally requested them, explicitly flushing session-specific information on user logout is a wise way to conserve space in the Satellite Server cache.

The following sections describe how to flush session information from Satellite Server.

This section contains the following topics:

9.7.1 Flushing a Session Via URL

You can flush all data pertaining to a particular session. You do this from WebCenter Sites by posting a form to a URL in the following format:



Table 9-6 Session Parameters

Parameter Value


Specify the name of the Satellite Server host whose cache is to be flushed


Specify 80 (the default) unless you re-configured Resin to run on a different port.


Specify the value assigned to the username property.


Use the value assigned to the password property.


Specify the session ID (the one maintained by WebCenter Sites, and not by Satellite Server) representing the session to be removed.

9.7.2 Flushing Current Session Information

To flush the information for the Satellite Server session that you are currently in, use the FlushServer URL with the current session's ID. The current session ID (ssid) is stored in a session variable with a name that is dependent upon your application server. You can see this name by looking at the session variable HTTP_COOKIE.

The following java code flushes the information for the current session:

String value;
String name = "WebLogicSession";
value = ics.GetVar(name);

String sFlushSessionUrl ="http://mysatellite:80/servlet/
reset=true&ssid=" + value;"
String sSatTest1Results = Utilities.readURL(sFlushSessionUrl);

9.7.3 Flushing Other Session Information

To flush information from a session other than the one you are in

  1. Add the following tag to the container page that contains the pagelets that you want to flush:

    cachecontrol="session:0:00:00 */*/*"/>

    The cachecontrol value of "session:0:00:00 */*/*" means that every session that requests this page creates a pagelet that can only be viewed by subsequent requests by that session. Once the session for a given page expires, that page cannot be viewed again. The container page will expire from the cache at midnight each day.

  2. After setting the cachecontrol parameter for the container page, use the Inventory servlet with the keys parameter to get its session ID (ssid). The ssid is the string that precedes the protocol and server name. For example, if the Inventory servlet displays:


    then the ssid is OuCOTrh9yporWfgu8U.

  3. Flush information from the session by using the ssid you found with the FlushServer URL. For example:



    You should have session affinity enabled if you want to flush information from a session other than the one you are in.