| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| |
| <document> |
| |
| <header> |
| <title>Session Logicsheet</title> |
| <authors> |
| <person name="Christopher Painter-Wakefield" email="paint007@mc.duke.edu"/> |
| </authors> |
| </header> |
| |
| <body> |
| |
| <s1 title="Description"> |
| |
| <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 |
| <link href="http://java.sun.com/products/servlet/2.2/javadoc/index.html"> |
| Java Servlet API Specification, version 2.2 |
| </link>) 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> |
| |
| </s1> |
| |
| <s1 title="Usage"> |
| |
| <p>As an XSP logicsheet, the Session logicsheet can only be used in an XSP page. |
| It may be helpful to be familiar with <link href="xsp.html">XSP</link> 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 |
| <code>create-session</code> 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> |
| |
| <source><![CDATA[ |
| <xsp:page |
| xmlns:xsp="http://apache.org/xsp" |
| xmlns:xsp-session="http://apache.org/xsp/session/2.0" |
| create-session="true"> |
| |
| ... |
| |
| </xsp:page> |
| ]]></source> |
| |
| <p>You may then use any of the elements in the <em>session</em> namespace described |
| in the <link href="session.html#elements">Elements Reference</link> section below.</p> |
| |
| </s1> |
| |
| <s1 title="Example Code"> |
| |
| <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> |
| |
| <source><![CDATA[ |
| <?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> |
| ]]></source> |
| |
| <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> |
| |
| </s1> |
| |
| <s1 title="XSP Interactions"> |
| |
| <p>The Session logicsheet tags may be used interchangeably with XSP code that |
| directly uses the <code>session</code> object. The <code>session</code> object |
| is an instance of the HttpSession class, and is available inside the user element |
| in an XSP page, if the <code>create-session</code> 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> |
| |
| <source> |
| <strong>Using the Session logicsheet:</strong> |
| <![CDATA[ |
| <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> |
| ]]></source> |
| |
| <source> |
| <strong>Using the session object:</strong> |
| <![CDATA[ |
| <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> |
| ]]></source> |
| |
| <p>You may freely mix Session elements with other XSP Java code, thus:</p> |
| |
| <source><![CDATA[ |
| <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> |
| ]]></source> |
| |
| </s1> |
| |
| <anchor id="elements"/> |
| <s1 title="Elements Reference"> |
| |
| <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> |
| |
| <source><![CDATA[ |
| <xsp-session:get-attribute name="fruit"/> |
| ]]></source> |
| |
| <source><![CDATA[ |
| <xsp-session:get-attribute><xsp-session:name>fruit</xsp-session:name></xsp-session:get-attribute> |
| ]]></source> |
| |
| <p>All Session elements which get data from the session can output the data |
| in two ways. The <code>as</code> attribute of the element is used to switch |
| between the different output options. The choice is always between some |
| default value for <code>as</code> and the value "node". Using the default |
| value for <code>as</code> (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 <code>as="node"</code>, |
| however, the output is embedded in a node or nodes, as appropriate. For instance, |
| the following code fragment:</p> |
| |
| <source><![CDATA[ |
| <xsp-session:get-attribute as="node" name="fruit"/> |
| ]]></source> |
| |
| <p>results in output similar to:</p> |
| |
| <source><![CDATA[ |
| <xsp-session:attribute name="fruit">apple</xsp-session:attribute> |
| ]]></source> |
| |
| <p>This is especially useful with elements that return multiple pieces of |
| information, such as <code>xsp-session:get-attribute-names</code>. Without using |
| <code>as="node"</code>, 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, <code>as</code> cannot be supplied as a child element; it |
| must be supplied as an attribute, if it is used at all.</p> |
| |
| |
| <note>Since these elements are primarily wrappers around HttpSession |
| methods, the HttpSession documentation in the |
| <link href="http://java.sun.com/products/servlet/2.2/javadoc/index.html"> |
| Java Servlet API Specification, version 2.2 |
| </link> |
| is also helpful in understanding the behavior and usage of these elements.</note> |
| |
| <table> |
| <caption>All of the Session logicsheet elements, in alphabetic order.</caption> |
| <tr> |
| <th>Element Name</th> |
| <th>Attributes/Child Elements</th> |
| <th>Node?</th> |
| <th>Description</th> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:get-attribute</td> |
| <td>name</td> |
| <td>yes</td> |
| <td>Gets the value of the named attribute stored in the session.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:get-attribute-names</td> |
| <td></td> |
| <td>yes</td> |
| <td>Gets the names of all attributes stored in the session.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:get-creation-time</td> |
| <td></td> |
| <td>yes</td> |
| <td>Gets the time when this session was created. The <code>as</code> attribute |
| for this element may be "long" (default), "string", or "node". If "long", |
| the returned value is a Java <code>long</code> that represents a Java <code>Date</code> |
| 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 <code>long</code> value is |
| output in the output node.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:get-id</td> |
| <td></td> |
| <td>yes</td> |
| <td>Gets the session id, generally a randomly generated string (server dependent).</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:get-last-accessed-time</td> |
| <td></td> |
| <td>yes</td> |
| <td>Gets the last time this session was accessed (the last time a page was |
| requested using this session id). The <code>as</code> attribute |
| for this element may be "long" (default), "string", or "node". If "long", |
| the returned value is a Java <code>long</code> that represents a Java <code>Date</code> |
| 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 <code>long</code> value is |
| output in the output node.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:get-max-inactive-interval</td> |
| <td></td> |
| <td>yes</td> |
| <td>Gets the minimum time, in seconds, that the server will maintain |
| this session between client requests.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:invalidate</td> |
| <td></td> |
| <td>no</td> |
| <td>Invalidates the current session. Any attributes stored in the session |
| are lost.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:is-new</td> |
| <td></td> |
| <td>yes</td> |
| <td>Indicates whether this session was just created.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:remove-attribute</td> |
| <td>name</td> |
| <td>no</td> |
| <td>Removes the named attribute from the session.</td> |
| </tr> |
| |
| <tr> |
| <td>xsp-session:set-attribute</td> |
| <td>name</td> |
| <td>no</td> |
| <td>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>xsp-session:set-max-inactive-interval</td> |
| <td>interval</td> |
| <td>no</td> |
| <td>Set the minimum time, in seconds, that the server should |
| maintain the current session between client requests.</td> |
| </tr> |
| |
| <tr> |
| <td>ignorethisitisjusttopreventwrapping</td> |
| <td></td> |
| <td></td> |
| <td></td> |
| </tr> |
| |
| </table> |
| |
| </s1> |
| |
| </body> |
| </document> |