| <!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"> |
| <xsp:page |
| xmlns:xsp="http://apache.org/xsp" |
| xmlns:xsp-session="http://apache.org/xsp/session/2.0" |
| create-session="true"> |
| |
| ... |
| |
| </xsp:page> |
| </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"> |
| <?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> |
| </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> |
| |
| <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> |
| </pre> |
| |
| |
| <pre class="code"> |
| |
| <strong>Using the session object:</strong> |
| |
| <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> |
| </pre> |
| |
| |
| <p>You may freely mix Session elements with other XSP Java code, thus:</p> |
| |
| |
| <pre class="code"> |
| <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> |
| </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"> |
| <xsp-session:get-attribute name="fruit"/> |
| </pre> |
| |
| |
| <pre class="code"> |
| <xsp-session:get-attribute><xsp-session:name>fruit</xsp-session:name></xsp-session:get-attribute> |
| </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 <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 <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"> |
| <xsp-session:get-attribute as="node" name="fruit"/> |
| </pre> |
| |
| |
| <p>results in output similar to:</p> |
| |
| |
| <pre class="code"> |
| <xsp-session:attribute name="fruit">apple</xsp-session:attribute> |
| </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., |
| <xsp-session:set-attribute name="fruit">apple</xsp-session:set-attribute>.</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> |