This chapter explains how to use XML tags to manage sessions and cookies.
This chapter contains the following sections:
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.
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:
Upon creating a session, WebCenter Sites automatically creates the following session variables:
Session Variable | What it Holds |
---|---|
|
The |
|
The comma-separated list of all ACLs to which this visitor belongs. If the visitor has not explicitly logged in, the default ACL is |
|
The username under which this visitor is logged in. If the visitor has not explicitly logged in, the default username is |
|
The name of the file containing WebCenter Sites properties. |
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:
A visitor first hits 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.
Here's a simple session example, consisting of three very short elements:
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:
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" 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 the following:
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>
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.
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:
CookieServer is a servlet that sets cookies for you. You access CookieServer by creating cookies with the satellite.cookie
tag.
WebCenter Sites offers two tags for managing cookies:
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:
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.
This example consists of several very short elements:
Element | What it Does |
---|---|
|
Determines whether a cookie is set. If cookie is set, call |
|
Displays a form that asks visitor to pick her favorite color. |
|
Creates a cookie on this visitor's browser. Then, redirects visitor to |
|
Displays a simple welcome message in the visitor's favorite color. |
This section contains the following topics:
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"> <THEN> <CALLELEMENT NAME="CSGuide/Sessions/DisplayWelcome"/> </THEN> <ELSE> <CALLELEMENT NAME="CSGuide/Sessions/ColorForm"/> </ELSE> </IF>
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> <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>
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).
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>
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.
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.
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:
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:
https://host:port/servlet/
FlushServer?reset=true&username=username&password=password& ssid=sessionID
where:
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. |
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/
FlushServer?username=ftuser&password=ftuser& reset=true&ssid=" + value;"
String sSatTest1Results = Utilities.readURL(sFlushSessionUrl);
To flush information from a session other than the one you are in
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:
You should have session affinity enabled if you want to flush information from a session other than the one you are in.