Session Logicsheet

Return-Path: Delivered-To: apmail-cocoon-cvs-archive@www.apache.org Received: (qmail 77092 invoked from network); 8 Sep 2007 20:19:41 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 8 Sep 2007 20:19:40 -0000 Received: (qmail 94048 invoked by uid 500); 8 Sep 2007 20:19:34 -0000 Delivered-To: apmail-cocoon-cvs-archive@cocoon.apache.org Received: (qmail 93976 invoked by uid 500); 8 Sep 2007 20:19:33 -0000 Mailing-List: contact cvs-help@cocoon.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@cocoon.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@cocoon.apache.org Received: (qmail 93965 invoked by uid 99); 8 Sep 2007 20:19:33 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 08 Sep 2007 13:19:33 -0700 X-ASF-Spam-Status: No, hits=-100.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 08 Sep 2007 20:19:37 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 90BBB1A9894; Sat, 8 Sep 2007 13:18:07 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r573901 [40/44] - in /cocoon/site: site/ site/2.0/ site/2.0/developing/ site/2.0/faq/ site/2.0/howto/chaperon/ site/2.0/installing/ site/2.0/plan/ site/2.0/snippet/ site/2.0/tutorial/ site/2.0/userdocs/ site/2.0/userdocs/actions/ site/2.0/u... Date: Sat, 08 Sep 2007 20:17:47 -0000 To: cvs@cocoon.apache.org From: asavory@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20070908201807.90BBB1A9894@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: cocoon/site/site/2.0/userdocs/xsp/session.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.0/userdocs/xsp/session.html?rev=573901&r1=573900&r2=573901&view=diff ============================================================================== --- cocoon/site/site/2.0/userdocs/xsp/session.html (original) +++ cocoon/site/site/2.0/userdocs/xsp/session.html Sat Sep 8 13:17:41 2007 @@ -1,703 +1,703 @@ - - - -Session Logicsheet - - - - - - - - - - - - - -

Session Logicsheet

- - - - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-XSP

-Logicsheets

Session

- - - - -

- - - - - -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. -

- - - -

- - - - -
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

- - - - - -

- - - - - - - -

- - + + + +Session Logicsheet + + + + + + + + + + + + + +

Session Logicsheet

+ + + + +

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

+XSP

+Logicsheets

Session

+ + + + +

+ + + + + +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. +

+ + + +

+ + + + +
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

+ + + + + +

+ + + + + + + +

+ +