Session Logicsheet

+ +

Description

The Session logicsheet (taglib) is an XSP logicsheet that wraps XML tags +around standard session operations. Specifically, the Session logicsheet +provides an XML interface to most methods of the HttpSession object (see the + Java +Servlet API Specification, version 2.2 ) for more information.

Each client gets its own unique session, which is created the first time it +accesses a page which creates or retrieves a session (see Usage, below). This +session is identified by a unique id, which is generated by the servlet server +and is passed back and forth to the client either as a cookie or as a parameter +in the request query string.

The Session logicsheet may be used to retrieve information about the session +itself, such as its creation time, and it may be used to store and retrieve +information in the session, such as a login name. The session will typically +become invalid after some length of time, releasing the stored information. You +can query whether a session is new and how long it will remain valid between +client requests, and you can also set how long the session should remain valid. +

+ +

Usage

As an XSP logicsheet, the Session logicsheet can only be used in an XSP page. +It may be helpful to be familiar with XSP before working +with this (or any) logicsheet.

To use the Session logicsheet, you must first declare the session +namespace, mapping it to the uri http://apache.org/xsp/session/2.0. +Also, to ensure that you have a session to work with, you must set the +create-session attribute in the xsp:page element to true. This will +retrieve the existing session, or create a new one if the current one is invalid +or doesn't exist. These steps will result in code like this:

+<xsp:page
+  xmlns:xsp="http://apache.org/xsp"
+  xmlns:xsp-session="http://apache.org/xsp/session/2.0"
+  create-session="true">
+
+...
+
+</xsp:page>
+

You may then use any of the elements in the session namespace +described in the Elements Reference section +below.

+ +

Example Code

The following code shows an example of using the Session logicsheet. This +code stores a value in the session under the name "fruit", then retrieves it +into the output. It also retrieves the creation time of the session as a String. +Of course, rather than displaying the retrieved values as we've done, you might +instead store them in elements and process them further, through an XSLT +stylesheet for instance.

+<?xml version="1.0"?>
+
+<xsp:page
+  xmlns:xsp="http://apache.org/xsp"
+  xmlns:xsp-session="http://apache.org/xsp/session/2.0"
+  create-session="true">
+
+  <html>
+    <xsp-session:set-attribute name="fruit">Apple</xsp-session:set-attribute>
+    <b>Your fruit is:</b> <xsp-session:get-attribute name="fruit"/>
+    <br/>
+    <b>Your session was created:</b> <xsp-session:get-creation-time as="string"/>
+  </html>
+
+</xsp:page>
+

The output of this page should look something like:

+Your fruit is: Apple

+Your session was created: Wed Jun 13 17:42:44 EDT 2001

+ +

XSP Interactions

The Session logicsheet tags may be used interchangeably with XSP code that +directly uses the session object. The session object is an +instance of the HttpSession class, and is available inside the user element in +an XSP page, if the create-session attribute of the xsp:page element +has been set to true. The Session logicsheet itself uses this object. Therefore, +the following code snippets function essentially the same:

+
+
+
+Using the Session logicsheet:
+
+<xsp:page
+  xmlns:xsp="http://apache.org/xsp"
+  xmlns:xsp-session="http://apache.org/xsp/session/2.0"
+  create-session="true">
+
+  <page>
+    <xsp-session:set-attribute name="fruit">Apple</xsp-session:set-attribute>
+    <fruit><xsp-session:get-attribute name="fruit"/></fruit>
+  </page>
+
+</xsp:page>
+

+
+
+
+Using the session object:
+
+<xsp:page
+  xmlns:xsp="http://apache.org/xsp"
+  xmlns:xsp-session="http://apache.org/xsp/session/2.0"
+  create-session="true">
+
+  <page>
+    session.setAttribute("fruit", "Apple");
+    <fruit><xsp:expr>session.getAttribute("fruit")</xsp:expr></fruit>
+  </page>
+
+</xsp:page>
+

You may freely mix Session elements with other XSP Java code, thus:

+<xsp:logic>
+  String fruit = <xsp-session:get-attribute name="fruit"/>;
+  if (fruit != null) {
+    fruit = fruit.toUpperCase();
+  }
+</xsp:logic>
+<fruit><xsp:expr>fruit</xsp:expr></fruit>
+

+ +

Elements Reference

All Session elements which require or allow for additional information allow +you to provide the information as either an attribute or a child element. These +attributes/child elements are listed in the "Attributes/Child Elements" column +of the table below. Unless noted, these are required for the given element; +their absence will result in Java compilation errors or exceptions.

The following fragments are equivalent:

+<xsp-session:get-attribute name="fruit"/>
+

+<xsp-session:get-attribute><xsp-session:name>fruit</xsp-session:name></xsp-session:get-attribute>
+

All Session elements which get data from the session can output the data in +two ways. The as attribute of the element is used to switch between the +different output options. The choice is always between some default value for +as and the value "node". Using the default value for as +(which is most easily achieved by leaving out the attribute altogether), the +Session element will put the result of its operation in an <xsp:expr> +node. This allows you to use the result in a Java expression, or converts it to +text in the output DOM tree. If you use as="node", however, the output +is embedded in a node or nodes, as appropriate. For instance, the following code +fragment:

+<xsp-session:get-attribute as="node" name="fruit"/>
+

results in output similar to:

+<xsp-session:attribute name="fruit">apple</xsp-session:attribute>
+

This is especially useful with elements that return multiple pieces of +information, such as xsp-session:get-attribute-names. Without using +as="node", the returned values are written out end to end without +separation. If node output is requested, however, each value is written out in a +separate node, which may then be referenced separately.

The elements which provide for node output are marked with a "yes" in the +"Node?" column of the table below. Unlike the other attributes used in Session +elements, as cannot be supplied as a child element; it must be supplied +as an attribute, if it is used at all.

Note

Since these elements are primarily wrappers around HttpSession +methods, the HttpSession documentation in the + Java +Servlet API Specification, version 2.2 is also helpful in understanding the +behavior and usage of these elements.

All of the Session logicsheet elements, in alphabetic order.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ + Element Name + +	+ + Attributes/Child Elements + +	+ + Node? + +	+ + Description + +
+ + xsp-session:get-attribute + +	+ + name + +	+ + yes + +	+ + Gets the value of the named attribute stored in the session. + +
+ + xsp-session:get-attribute-names + +		+ + yes + +	+ + Gets the names of all attributes stored in the session. + +
+ + xsp-session:get-creation-time + +		+ + yes + +	+ + Gets the time when this session was created. The `as` attribute for +this element may be "long" (default), "string", or "node". If "long", the +returned value is a Java `long` that represents a Java `Date` +value. If "string", the value is converted to a String representation of the +date, e.g., "Wed Jun 13 15:57:06 EDT 2001". If "node", the `long` value +is output in the output node. + +
+ + xsp-session:get-id + +		+ + yes + +	+ + Gets the session id, generally a randomly generated string (server +dependent). + +
+ + xsp-session:get-last-accessed-time + +		+ + yes + +	+ + Gets the last time this session was accessed (the last time a page was +requested using this session id). The `as` attribute for this element may +be "long" (default), "string", or "node". If "long", the returned value is a +Java `long` that represents a Java `Date` value. If "string", the +value is converted to a String representation of the date, e.g., "Wed Jun 13 +15:57:06 EDT 2001". If "node", the `long` value is output in the output +node. + +
+ + xsp-session:get-max-inactive-interval + +		+ + yes + +	+ + Gets the minimum time, in seconds, that the server will maintain this session +between client requests. + +
+ + xsp-session:invalidate + +		+ + no + +	+ + Invalidates the current session. Any attributes stored in the session are +lost. + +
+ + xsp-session:is-new + +		+ + yes + +	+ + Indicates whether this session was just created. + +
+ + xsp-session:remove-attribute + +	+ + name + +	+ + no + +	+ + Removes the named attribute from the session. + +
+ + xsp-session:set-attribute + +	+ + name + +	+ + no + +	+ + Stores a named attribute in the session. Place the value to be stored as the +text contents of this element, e.g., <xsp-session:set-attribute +name="fruit">apple</xsp-session:set-attribute>. + +
+ + xsp-session:set-max-inactive-interval + +	+ + interval + +	+ + no + +	+ + Set the minimum time, in seconds, that the server should maintain the current +session between client requests. + +
+ + ignorethisitisjusttopreventwrapping + +

+Errors and Improvements? + If you see any errors or potential improvements in this document + please help us: + + View, Edit or comment on + the latest development version (registration required). +

+ +