About Sessions and Cookies

17.1 About Sessions

Sessions are necessary when a web server managing a website uses HTTP stateless protocol that doesn’t require the server to retain the session information. The application server starts a session as soon as a visitor begins browsing through pages. The browsing information gets stored in session variables.

Imagine a website containing two pages: main and water. Suppose a visitor sees main first and then moves on to water. 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.

17.2 Session Lifetime

A session begins when a visitor first visits your website. It ends when the visitor terminates his browser, the system administrator stops the application server, or 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.

See these topics:

17.2.1 Session Variables Maintained by WebCenter Sites

Upon creating a session, WebCenter Sites automatically creates the session variables described in this table:

Table 17-1 Session Variables

Session Variable	What it Holds
`SessionVariables.currentUser`	The `id` of the visitor logged in.
`SessionVariables.currentAcl`	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`.
`SessionVariables.username`	The user name under which this visitor is logged in. If the visitor has not explicitly logged in, the default user name is `DefaultReader`.
`SessionVariables.iniFile`	The name of the file containing WebCenter Sites properties.

17.2.2 Logging In and Logging Out

When a visitor first visits 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 before 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 before login. For example, consider the following sequence:

A visitor first visits a page, so the value of SessionVariables.username is DefaultReader.
The visitor logs in as marilyn, so the value of SessionVariables.username is marilyn.
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.

17.3 Sessions Example

A simple session example with a few elements can help you understand how sessions work.

Here's an example, consisting of three very short elements:

Table 17-2 Sessions Example

Element	What it Does
`FeelingsForm`	Asks visitors to pick their current mood.
`SetFeelings`	Assigns the current mood to a session variable.
`Meat`	Evaluates the session variable.

See these topics:

17.3.1 FeelingsForm Element

The feelings form does not 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" 
          value="CSGuide/Sessions/SetFeelings"/>

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

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

The resulting page looks like this:

Figure 17-1 Sample Page

Description of "Figure 17-1 Sample Page"

17.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. 
</A></P>

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"/>
</P>

17.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">
 <THEN>
     <P>Sessions are happiness.</P>
 </THEN>
 <ELSE>
     <P>Don't let sessions get you down.</P>
 </ELSE>
</IF>

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.

17.4 About Cookies

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 includes the following topics:

17.4.1 CookieServer

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

17.4.2 Cookie Tags

WebCenter Sites offers two tags for managing cookies:

Table 17-3 Cookie Tags

Tag	Use
`satellite.cookie`	Sets a cookie on the client's browser.
`REMOVECOOKIE`	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 17-4 Cookie Attributes

Attribute	Value
`name`	Name of the cookie. This also serves as the name of the incoming variable containing the value of the cookie. Note: 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.
`expiration`	Time in seconds after which the cookie no longer is sent to the web server.
`security`	Optionally set security on the cookie.
`URL`	Restrict that the cookie only be sent on this URL.
`Domain`	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.

17.5 Cookie Example

A cookie example with several short elements can help you understand how cookies work.

Here is an example:

Table 17-5 Cookie Elements

Element	What it Does
`Start`	Determines whether a cookie is set. If cookie is set, call `DisplayWelcome`. If cookie is not set, call `GetColorPreference`.
`ColorForm`	Displays a form that asks visitor to pick her favorite color.
`CreateCookie`	Creates a cookie on this visitor's browser. Then, redirects visitor to `DisplayWelcome`.
`DisplayWelcome`	Displays a simple welcome message in the visitor's favorite color.

See these topics:

17.5.1 Start.xml

The Start.xml element determines whether the cookie has 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">
 <THEN> 
    <CALLELEMENT NAME="CSGuide/Sessions/DisplayWelcome"/>
 </THEN>
 <ELSE>
    <CALLELEMENT NAME="CSGuide/Sessions/ColorForm"/>
 </ELSE>
</IF>

17.5.2 ColorForm

The ColorForm.xml element displays 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>
 <P>
 <select name="FavoriteColor" size="1">
    <option>Red</option>
    <option>Green</option>
    <option>Blue</option>
 </select>
 </P>

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

17.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).

17.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"
     REPLACEALL="Variables.ColorCookie">
Displaying a Friendly Welcome.
</font></H1>

17.5.5 Running the Cookie Example

To run the cookie example, use your browser to go to the following pagename: CSGuide/Sessions/Start.

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

17.6 Tips and Tricks

Some tips and tricks about using sessions can help you improve visitors’ browsing experience while efficiently using the system resources.

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.

17.7 Satellite Server Session Tracking

Websites that present personalized content to visitors must track sessions. WebCenter Sites and Satellite Server both track sessions and set two cookies in the visitor's browser. Each cookie independently tracks a session. This redundancy is useful to maintain aWebCenter Sites session when a Satellite Server goes down.

Though Satellite Server will only serve session-specific pagelets back to the person who originally requested them, explicitly flushing session-specific information about 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:

17.7.1 Flushing a Session Using a URL

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

https://host:port/servlet/FlushServer?reset=true&username=username&password=password&ssid=sessionID

where:

Table 17-6 Session Parameters

Parameter	Value
`host`	Specify the name of the Satellite Server host whose cache is to be flushed.
`port`	Specify 80 (the default) unless you re-configured Resin to run on a different port.
`username`	Specify the value assigned to the user name property.
`password`	Use the value assigned to the password property.
`sessionID`	Specify the session ID (the one maintained by WebCenter Sites, and not by Satellite Server) representing the session to be removed.

17.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.

Use the following Java code to flush the information for the current session:

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

String sFlushSessionUrl ="http://mysatellite:80/servlet/
FlushServer?username=ftuser&password=ftuser&
reset=true&ssid=" + value;"

String sSatTest1Results = Utilities.readURL(sFlushSessionUrl);

17.7.3 Flushing Other Session Information

To flush information from a session other than the one you are in follow these steps:

Add the following tag to the container page that contains the pagelets that you want to flush:
```
<satellite.page 
pagename="QA/Satellite/Functional/xml/pagelet4" 
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.
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:
```
OuCOTrh9yporWfgu8Uthttp://myserver:80/servlet/
ContentServer?pagename=QA/Satellite/Functional/xml/pagelet4
```
then the ssid is OuCOTrh9yporWfgu8U.
Flush information from the session by using the ssid you found with the FlushServer URL. For example:
```
http://myserver:80/servlet/
FlushServer?username=ftuser&password=ftuser&reset=true&
ssid=OuCOTrh9yporWfgu8U
```
Note:

To flush information from a session other than the one you are in, you should have session affinity enabled.