blob: 6c151bf0b8e1fe586570ce8a445741a05a245cd1 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Session Logicsheet</title>
<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
<meta content="Christopher Painter-Wakefield" name="DC.Creator">
</head>
<body>
<h1>Description</h1>
<p>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
<a class="external" href="http://java.sun.com/products/servlet/2.2/javadoc/index.html">
Java Servlet API Specification, version 2.2
</a>) for more information.</p>
<p>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.</p>
<p>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.</p>
<h1>Usage</h1>
<p>As an XSP logicsheet, the Session logicsheet can only be used in an XSP page.
It may be helpful to be familiar with <a href="xsp.html">XSP</a> before
working with this (or any) logicsheet.</p>
<p>To use the Session logicsheet, you must first declare the <em>session</em>
namespace, mapping it to the uri <em>http://apache.org/xsp/session/2.0</em>.
Also, to ensure that you have a session to work with, you must set the
<span class="codefrag">create-session</span> 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:</p>
<pre class="code">
&lt;xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-session="http://apache.org/xsp/session/2.0"
create-session="true"&gt;
...
&lt;/xsp:page&gt;
</pre>
<p>You may then use any of the elements in the <em>session</em> namespace described
in the <a href="session.html#elements">Elements Reference</a> section below.</p>
<h1>Example Code</h1>
<p>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.</p>
<pre class="code">
&lt;?xml version="1.0"?&gt;
&lt;xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-session="http://apache.org/xsp/session/2.0"
create-session="true"&gt;
&lt;html&gt;
&lt;xsp-session:set-attribute name="fruit"&gt;Apple&lt;/xsp-session:set-attribute&gt;
&lt;b&gt;Your fruit is:&lt;/b&gt; &lt;xsp-session:get-attribute name="fruit"/&gt;
&lt;br/&gt;
&lt;b&gt;Your session was created:&lt;/b&gt; &lt;xsp-session:get-creation-time as="string"/&gt;
&lt;/html&gt;
&lt;/xsp:page&gt;
</pre>
<p>The output of this page should look something like:</p>
<p>
<strong>Your fruit is:</strong> Apple</p>
<p>
<strong>Your session was created:</strong> Wed Jun 13 17:42:44 EDT 2001</p>
<h1>XSP Interactions</h1>
<p>The Session logicsheet tags may be used interchangeably with XSP code that
directly uses the <span class="codefrag">session</span> object. The <span class="codefrag">session</span> object
is an instance of the HttpSession class, and is available inside the user element
in an XSP page, if the <span class="codefrag">create-session</span> 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:</p>
<pre class="code">
<strong>Using the Session logicsheet:</strong>
&lt;xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-session="http://apache.org/xsp/session/2.0"
create-session="true"&gt;
&lt;page&gt;
&lt;xsp-session:set-attribute name="fruit"&gt;Apple&lt;/xsp-session:set-attribute&gt;
&lt;fruit&gt;&lt;xsp-session:get-attribute name="fruit"/&gt;&lt;/fruit&gt;
&lt;/page&gt;
&lt;/xsp:page&gt;
</pre>
<pre class="code">
<strong>Using the session object:</strong>
&lt;xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-session="http://apache.org/xsp/session/2.0"
create-session="true"&gt;
&lt;page&gt;
session.setAttribute("fruit", "Apple");
&lt;fruit&gt;&lt;xsp:expr&gt;session.getAttribute("fruit")&lt;/xsp:expr&gt;&lt;/fruit&gt;
&lt;/page&gt;
&lt;/xsp:page&gt;
</pre>
<p>You may freely mix Session elements with other XSP Java code, thus:</p>
<pre class="code">
&lt;xsp:logic&gt;
String fruit = &lt;xsp-session:get-attribute name="fruit"/&gt;;
if (fruit != null) {
fruit = fruit.toUpperCase();
}
&lt;/xsp:logic&gt;
&lt;fruit&gt;&lt;xsp:expr&gt;fruit&lt;/xsp:expr&gt;&lt;/fruit&gt;
</pre>
<a name="elements"></a>
<h1>Elements Reference</h1>
<p>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.</p>
<p>The following fragments are equivalent:</p>
<pre class="code">
&lt;xsp-session:get-attribute name="fruit"/&gt;
</pre>
<pre class="code">
&lt;xsp-session:get-attribute&gt;&lt;xsp-session:name&gt;fruit&lt;/xsp-session:name&gt;&lt;/xsp-session:get-attribute&gt;
</pre>
<p>All Session elements which get data from the session can output the data
in two ways. The <span class="codefrag">as</span> attribute of the element is used to switch
between the different output options. The choice is always between some
default value for <span class="codefrag">as</span> and the value "node". Using the default
value for <span class="codefrag">as</span> (which is most easily achieved by leaving out the
attribute altogether), the Session element will put the result of its operation
in an &lt;xsp:expr&gt; 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 <span class="codefrag">as="node"</span>,
however, the output is embedded in a node or nodes, as appropriate. For instance,
the following code fragment:</p>
<pre class="code">
&lt;xsp-session:get-attribute as="node" name="fruit"/&gt;
</pre>
<p>results in output similar to:</p>
<pre class="code">
&lt;xsp-session:attribute name="fruit"&gt;apple&lt;/xsp-session:attribute&gt;
</pre>
<p>This is especially useful with elements that return multiple pieces of
information, such as <span class="codefrag">xsp-session:get-attribute-names</span>. Without using
<span class="codefrag">as="node"</span>, 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.</p>
<p>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, <span class="codefrag">as</span> cannot be supplied as a child element; it
must be supplied as an attribute, if it is used at all.</p>
<div class="note">Since these elements are primarily wrappers around HttpSession
methods, the HttpSession documentation in the
<a class="external" href="http://java.sun.com/products/servlet/2.2/javadoc/index.html">
Java Servlet API Specification, version 2.2
</a>
is also helpful in understanding the behavior and usage of these elements.</div>
<table>
All of the Session logicsheet elements, in alphabetic order.
<tr>
<th colspan="1" rowspan="1">Element Name</th>
<th colspan="1" rowspan="1">Attributes/Child Elements</th>
<th colspan="1" rowspan="1">Node?</th>
<th colspan="1" rowspan="1">Description</th>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:get-attribute</td>
<td colspan="1" rowspan="1">name</td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Gets the value of the named attribute stored in the session.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:get-attribute-names</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Gets the names of all attributes stored in the session.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:get-creation-time</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Gets the time when this session was created. The <span class="codefrag">as</span> attribute
for this element may be "long" (default), "string", or "node". If "long",
the returned value is a Java <span class="codefrag">long</span> that represents a Java <span class="codefrag">Date</span>
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 <span class="codefrag">long</span> value is
output in the output node.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:get-id</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Gets the session id, generally a randomly generated string (server dependent).</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:get-last-accessed-time</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Gets the last time this session was accessed (the last time a page was
requested using this session id). The <span class="codefrag">as</span> attribute
for this element may be "long" (default), "string", or "node". If "long",
the returned value is a Java <span class="codefrag">long</span> that represents a Java <span class="codefrag">Date</span>
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 <span class="codefrag">long</span> value is
output in the output node.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:get-max-inactive-interval</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Gets the minimum time, in seconds, that the server will maintain
this session between client requests.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:invalidate</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">no</td>
<td colspan="1" rowspan="1">Invalidates the current session. Any attributes stored in the session
are lost.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:is-new</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1">yes</td>
<td colspan="1" rowspan="1">Indicates whether this session was just created.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:remove-attribute</td>
<td colspan="1" rowspan="1">name</td>
<td colspan="1" rowspan="1">no</td>
<td colspan="1" rowspan="1">Removes the named attribute from the session.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:set-attribute</td>
<td colspan="1" rowspan="1">name</td>
<td colspan="1" rowspan="1">no</td>
<td colspan="1" rowspan="1">Stores a named attribute in the session. Place the value
to be stored as the text contents of this element, e.g.,
&lt;xsp-session:set-attribute name="fruit"&gt;apple&lt;/xsp-session:set-attribute&gt;.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">xsp-session:set-max-inactive-interval</td>
<td colspan="1" rowspan="1">interval</td>
<td colspan="1" rowspan="1">no</td>
<td colspan="1" rowspan="1">Set the minimum time, in seconds, that the server should
maintain the current session between client requests.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">ignorethisitisjusttopreventwrapping</td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1"></td>
<td colspan="1" rowspan="1"></td>
</tr>
</table>
</body>
</html>