| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| <document> |
| <header> |
| <title>Session Contexts</title> |
| <authors> |
| <person name="Carsten Ziegeler" email="cziegeler@s-und-n.de"/> |
| </authors> |
| </header> |
| <body> |
| <s1 title="Introduction"> |
| <p>This chapter describes the concept of the session context provided |
| by the session framework (session-fw block).</p> |
| <p>The session framework provides the concept of so called (session) contexts. |
| A session context is a data storage in the session that can contain |
| arbitrary data in XML format.</p> |
| <p>You can define your own contexts for your application. For example, |
| if you build a web shop, you can create a context called <em>shop</em> |
| and store the basket of the user in it.</p> |
| <p>The <em>session transformer</em> is the main component used for |
| storing and retrieving information from such a context.</p> |
| <note>The chapter "Special Contexts" explains some special |
| contexts which do not require a session. They are available everytime. These |
| special contexts are the request context and the |
| temporary context.</note> |
| </s1> |
| <s1 title="session Transformer"> |
| <p>The <em>session transformer</em> is responsible for interpreting the tags |
| and performing the actions required. The session transformer is configured |
| in the sitemap and can be used inside a pipeline. All tags must be prefixed |
| with the session namespace. So the actual tag used in the document will read |
| <em><session:xxxx></em>. The current namespace URI for the session |
| transformer is <em>"http://apache.org/cocoon/session/1.0"</em>.</p> |
| <s2 title="Context-Tags"> |
| <p>A context is basically an application specific block of XML data in |
| the users session. Each context has a unique name.</p> |
| <p>The command <em>createcontext</em> is used to create a new context. |
| A <em>name</em> attribute must be given to the context in order to identify it. |
| The following names may not be used: request, response, session, |
| context, temp, portal or authentication. If a context of the same name already exists |
| then this command will have no effect.</p> |
| <p><em><createcontext name="mycontext"/></em></p> |
| <p>In order to delete a context the command <em>deletecontext</em> is |
| provided. Again a <em>name</em> attribute must be provided.</p> |
| <p><em><deletecontext name="mycontext"/></em></p> |
| <p>Once created, XML data can then be stored inside or read from a |
| given context.</p> |
| </s2> |
| <s2 title="Accessing context data"> |
| <p>The data in a context can be dynamically accessed using the |
| following commands.</p> |
| <p></p> |
| <p><em>getxml</em> allows data to be read out of a context. A |
| <em>path</em> attribute describes the source of the data inside the context and |
| consists of an XPath expression. All <em>path</em> values must be absolute and |
| only nodes and attributes can be accessed. </p> |
| <p>An optional default value can also be provided to allow for the |
| nonexistence of the requested data.</p> |
| <p><em><getxml context="mycontext" |
| path="/User/Name"/></em></p> |
| <p><em><getxml context="mycontext" |
| path="/User/Name">Matthew</getxml></em></p> |
| <p>Attributes can also be accessed.</p> |
| <p><em><getxml context="mycontext" |
| path="/User/Name/@Age"/></em></p> |
| <p><em></em></p> |
| <p>Data can be written into a context using the <em>setxml</em> |
| command. It is possible to set values or nodes as the following examples |
| show.</p> |
| <p><em><setxml context="mycontext" |
| path="/User/Name"/>Carsten</setxml></em></p> |
| <p><em><setxml context="mycontext" |
| path="/User/"/><Name>Carsten</Name></setxml></em></p> |
| <p></p> |
| <p>Using the <em>setxml</em> command causes all the nodes below the |
| target node to be deleted. If you wish to maintain the nodes and manipulate |
| individual branches of the XML tree - then the session transformer offers the |
| <em>mergexml</em> command.</p> |
| <p></p> |
| <p>Use the <em>removexml</em> command to remove nodes from the |
| context.</p> |
| <p><em><removexml context="mycontext" |
| path="/User/"/></em></p> |
| <s3 title="Example"> |
| <p>The following example shows the use of several commands and in |
| particular how the <em>mergexml</em> command can be used to manipulate context |
| data.</p> |
| <source><resource xmlns:session="http://apache.org/cocoon/session/1.0"> |
| <session:createcontext name="trackdemo"/> |
| <!-- build context data --> |
| <session:setxml context="trackdemo" path="/"> |
| <context> |
| <users> |
| <user id="1"> |
| <name>Carsten</name> |
| </user> |
| </users> |
| </context> |
| </session:setxml> |
| <session:mergexml context="trackdemo" path="/context"> |
| <users> |
| <user id="1"> |
| <name>Ziegeler</name> |
| <developer>true</developer> |
| </user> |
| <user id="2"> |
| <name>Walter</name> |
| </user> |
| </users> |
| </session:mergexml> |
| <session:getxml context="trackdemo" path="/"/> |
| </resource></source> |
| <p>In the above example, a context for storing data is added. Using |
| the <em>setxml</em> command data is then stored into the context. The following |
| <em>mergexml</em> command then changes the name of user-1 and adds a further |
| tag. As there is no original user-2 the complete subtree is then added to the |
| context.</p> |
| </s3> |
| </s2> |
| <s2 title="Reading and writing contexts"> |
| <p>Aside from the described means of accessing data in a context, |
| the session transformer also provides for the reading and writing of contexts. This can be |
| used to write an application context out to a database or to read an |
| application context in from a file.</p> |
| <p>The session transformer offers a very flexible way of defining the source of the |
| context data. It is possible to specify a resource (defined in the sitemap) or |
| a Java class. Using a resource allows for example the context data to be read |
| from a database using the SQL Transformer. As this source is a Cocoon |
| pipeline, the data can be generated and transformed before passing into the |
| context. </p> |
| <p>When a context is created, it can get additional save and load URIs |
| which are used for loading/saving to/from the context:</p> |
| <p><em><createcontext name="mycontext" load="cocoon://load-from-db" |
| save="cocoon://save-to-db"/></em></p> |
| <p>These URIs can then be used inside a document to load data into a |
| context:</p> |
| <p><em><loadxml context="mycontext"/></em></p> |
| <p>This example would then load the context data via the resource |
| <em>load-from-db</em> which must be defined in the sitemap.</p> |
| <p>Parameters can be passed to and interpreted by the uri or the Java |
| class. This allows the context data to be read dependent on say the current |
| user.</p> |
| <p><em><loadxml |
| context="mycontext"><user>ben</user></loadxml></em></p> |
| |
| <p>The resource addressed by the uri will receive the parameters as |
| request-parameters. In addition the name of the context will always be passed |
| as <em>contextname</em>.</p> |
| <p>Writing context data works in the same manner.</p> |
| <p><em><savexml context="mycontext"/></em></p> |
| <p>Both commands can use the optional <em>path</em> attribute:</p> |
| <p><em><loadxml context="mycontext" path="/user"/></em></p> |
| <p><em><savexml context="mycotnext" path="/user"/></em></p> |
| <p>The first command will read xml from the uri and store it in the |
| context under the node <em>user</em>, the second one saves only the xml subtree |
| under the node <em>user</em> to the uri. The resource addressed by the uri will |
| be passed in addition to the <em>contextname</em> parameter the <em>path</em> |
| parameter with the corresponding value. If the <em>path</em> attribute is not |
| present the <em>path</em> parameter will get the value <em>"/"</em>.</p> |
| </s2> |
| </s1> |
| <s1 title="Special Contexts"> |
| <p>Cocoon creates and maintains special contexts that allow the |
| applications to access the environment. This allows the read-only access |
| to such things as the current request using the same XPath |
| commands previously described. These context do not require any session, they |
| are always available and change on every request.</p> |
| <s2 title="The Request Context - Accessing the Environment, Part One"> |
| <p>The request context is an XML description of the current |
| (HTTP) request. This context is a special read only context that |
| can be accessed with the usual commands:</p> |
| <p><em><getxml context="request" path="/parameter"/></em></p> |
| |
| <p>For example, if you want to get the value of a parameter with the |
| name <em>username</em> you can include the following command in your XML and it |
| will be replaced with the value of the parameter:</p> |
| <p><em><getxml context="request" |
| path="/parameter/username"/></em></p> |
| <p>If you wish to obtain the complete querystring as it was |
| passed into Cocoon - without converting the data to XML - then you can use |
| the "/querystring" path:</p> |
| <p><em><getxml context="request" |
| path="/querystring"/></em></p> |
| <p>The result will be a string in the format |
| "?param=aaa&...".</p> |
| <p>The complete context you can access via these commands has the |
| following XML format:</p> |
| <source><parameter> |
| <!-- All parameters: parameter names build the elements with the value of the first parameter with |
| this name as text node child --> |
| <firstparameter>value of parameter</firstparameter> |
| <secondparameter>value of parameter</secondparameter> |
| </parameter> |
| |
| <querystring>the querystring with a leading '?' or empty<querystring> |
| (The querystring contains only parameters send by the GET method) |
| |
| <parametervalues> |
| <!-- All parameters. The tags are all inside the cinclude transformer namespace. |
| The generated XML can be used without modification for the |
| cinclude:includexml command. --> |
| <cinclude:parameters> |
| <cinclude:parameter> |
| <cinclude:name>1st parameter name</cinclude:name> |
| <cinclude:value>1st parameter value</cinclude:value> |
| </cinclude:parameter> |
| ... |
| <cinclude:parameter> |
| <cinclude:name>2nd parameter name</cinclude:name> |
| <cinclude:value>2nd parameter value</cinclude:value> |
| </cinclude:parameter> |
| </cinclude:parameters> |
| <!-- If a parameter has more than one value, for each value a |
| <session:param> block is generated. --> |
| </parametervalues> |
| |
| <attributes> |
| <!-- lists all attributes, attribute names build the elements |
| with the values as text node childs --> |
| </attributes> |
| |
| <headers> |
| <!-- lists all headers, header names build the elements |
| with the values as text node childs --> |
| </headers> |
| |
| <cookies> |
| <!-- lists all cookies --> |
| <cookie name="..."> |
| <value>the cookie value</value> |
| <name>the name of the cookie</name> |
| <comment>value</comment> |
| <domain>value</domain> |
| <path>value</path> |
| <maxAge>value</maxAge> |
| <secure>value</secure> |
| <version>value</version> |
| </cookie> |
| </cookies> |
| |
| <characterEncoding>value</characterEncoding> |
| <contentLength>value</contentLength> |
| <contentType>value</contentType> |
| <protocol>value</protocol> |
| <remoteAddress>value</remoteAddress> |
| <remoteHost>value</remoteHost> |
| <scheme>value</scheme> |
| <serverName>value</serverName> |
| <serverPort>value</serverPort> |
| <method>value</method> |
| <contextPath>value</contextPath> |
| <pathInfo>value</pathInfo> |
| <pathTranslated>value</pathTranslated> |
| <remoteUser>value</remoteUser> |
| <requestedSessionId>value</requestedSessionId> |
| <requestURI>value</requestURI> |
| <servletPath>value</servletPath> |
| <isRequestedSessionIdFromCookie>value</isRequestedSessionIdFromCookie> |
| <isRequestedSessionIdFromCookie>value</isRequestedSessionIdFromCookie> |
| <isRequestedSessionIdValid>value</isRequestedSessionIdValid></source> |
| </s2> |
| <s2 title="The Temporary Context"> |
| <p>The temporary context with the name <em>temporary</em> is available on |
| each request. It is independent from the session and has no content when a new |
| request starts. It can be used like any other context except that the content |
| is lost/deleted when the current response is finished.</p> |
| <p>Using the tempory context it is possible to store any XML |
| information for processing the current request.</p> |
| </s2> |
| </s1> |
| <s1 title="Session-Context Input Module"> |
| <p>In addition to the <em>session transformer</em>, the <em>session-context input module</em> |
| can be used directly in the sitemap to get information out of a context.</p> |
| <p>The information for the input module consists of two parts, the first |
| one being the context name and the second one the path inside the |
| context. Let's have a look at an example:</p> |
| <source> |
| <map:generate src="{session-context:request/method}.xml"/> |
| </source> |
| <p> |
| In the example above, either <em>GET.xml</em> or <em>POST.xml</em> is |
| read by the <em>file generator</em>, depending on the value from |
| the context <em>request</em> using the xpath <em>method</em>. |
| </p> |
| </s1> |
| </body> |
| </document> |