[ You are here: XTF -> Programming -> Tracking Session State ]

Tracking Session State

Table of Contents

Tracking Session State
Enabling Session Tracking
Storing and Retrieving Session Data
The Session ID and How it is Tracked
URL Encoding of the Session ID
Getting the session ID
Checking Whether Session Tracking is Enabled
In general, crossQuery and dynaXML are "stateless", that is, they don't remember anything from one request to the next. Any given URL request is treated separately, and all the servlet knows is what is present in the URL parameters.
URL parameters are fine for small pieces of data that change frequently, such as query parameters, page number, document ID, etc. However they're cumbersome for large amounts of data, or information that doesn't change frequently. This is where XTF's Session State Tracking facilities come in handy.

When session tracking is enabled (as it is by default), XTF will associate a session ID with the first request made by a particular user. As the user clicks on links from that page, the session ID will automatically track along with each page view. Your parsing and formatting stylesheets can store and retrieve data in the session, and this data will be available on subsequent requests.

A brief tutorial on session tracking follows; details of the functions are detailed in the Session State section of the XTF Stylesheet Reference.

Enabling Session Tracking

Before attempting to store or retrieve session data, you must enable session tracking in the configuration file of the servlet(s) you're using (i.e. dynaXML.conf and/or crossQuery.conf). The line to enable tracking looks like this:
<trackSessions track="yes"/>

Storing and Retrieving Session Data

Once enabled, XTF's built-in XSL extension functions can be used to store or retrieve data in the session associated with a given request. For example, here's some XSL code to store a value in the session:
<xsl:stylesheet xmlns:session="java:org.cdlib.xtf.xslt.Session">
...
  <xsl:value-of select="session:setData('someName', 'someValue')">
As you see, the session:setData function can be used like any other XPath function, as long as the proper namespace has been declared. It places data into the session under the given name (replacing any previous data with that name.)

In general the session data can contain as many name/value pairs as you wish to place into it. The value can be either a string or structured XML; if you use XML that contains more than one element, be sure to include a single outer wrapper element as in the following example:
<xsl:variable name="newValue">
  <myWrapper>
    <element1>...</element1>
    <element2>...</element2>
    ...
  </myWrapper>
</xsl:variable>
 
<xsl:value-of select="session:setData('someName', $newValue)">
Retrieving session data is also very simple:
<xsl:variable name="myData" select="session:getData('someName')">
The session:getData function retrieves the data value established for this name by session:setData. If no data was previously stored under that name, null is returned. (i.e. empty string/empty sequence).

The Session ID and How it is Tracked

XTF automatically creates and tracks session identifiers for you. In general you don't have to do any additional work for this to happen transparently in the background. However, one case may require more work.

By default, when session tracking is enabled, XTF attempts to set a cookie in the user's browser. This cookie simply contains the session ID, and is timed to expire at the end of the user's browsing session. On subsequent requests, the browser will automatically return the cookie to XTF, providing the session ID.

However, some users disable cookies due to privacy concerns. If XTF detects that the cookie was not accepted, it automatically switches to using the URL to store the session identifier. Typically you'll see ;jsessionid=xxxxx added to the URL in this case, just before the '?' that begins the normal URL parameters.

URL Encoding of the Session ID

When URL encoding is activated, XTF automatically intercepts URLs that your stylesheets produce as part of <form>, <a>, and <frame> elements in the output HTML. XTF will then add the session ID to the URLs as appropriate.

Though not common, if your HTML output contains URLs as part of other elements or in JavaScript calls, then you'll need to inform XTF that these URLs may need to have the session ID added. This is done using the session:encodeURL function like this:
<xsl:variable name="originalURL" select="some value here"/>
<xsl:variable name="encodedURL" select="session:encodeURL($originalURL)"/>
XTF will check the URL and if it points to an XTF servlet and the session ID needs to be tracked in the URL, it will return a modified version of the URL that contains the session ID.

Getting the session ID

You may want to record the identifier of the current session for reference in a database. To obtain the identifier, use code like this:
<xsl:variable name="sessionID" select="session:getID()"/>

Checking Whether Session Tracking is Enabled

If you wish, you can create stylesheet code that works differently depending on whether session tracking is enabled in the configuration file for the particular servlet you're working in. It looks like this:
<xsl:if test="session:isEnabled()">
  <!-- Do session-related stuff here -->
</xsl:if>