/ 
AxKit-XSP-Session-0.11
River stage zero No dependents
/ AxKit::XSP::Session

NAME

AxKit::XSP::Session - Session wrapper tag library for AxKit eXtesible Server Pages.

SYNOPSIS

Add the session: namespace to your XSP <xsp:page> tag:

<xsp:page
     language="Perl"
     xmlns:xsp="http://apache.org/xsp/core/v1"
     xmlns:session="http://www.apache.org/1999/XSP/Session"
>

And add this taglib to AxKit (via httpd.conf or .htaccess):

AxAddXSPTaglib AxKit::XSP::Session

DESCRIPTION

The XSP session: taglib provides basic session object operations to XSP, using the Cocoon2 Session taglib specification. I tried to stay as close to the Cocoon2 specification as possible, for compatibility reasons. However, there are some tags that either didn't make sense to implement, or I augmented since I was there.

Keep in mind, that currently this taglib does not actually create or fetch your session for you. That has to happen outside this taglib. This module relies on the $r->pnotes() table for passing the session object around.

Special thanks go out to Kip Hampton for creating AxKit::XSP::Sendmail, from which I created AxKit::XSP::Session.

Tag Reference

<session:get-attribute>

This is the most used tag. It accepts either an attribute or child node called 'name'. The value passed in 'name' is used as the key to retrieve data from the session object.

<session:set-attribute>

Similar to :get-attribute, this tag will set an attribute. It accepts an additional parameter (as an attribute or child node) called 'value'. You can intermix attribute and child nodes for either parameter, so its pretty flexible. NOTE: this is different from Cocoon2, where the value is a child text node only.

<session:get-id>

Gets the SessionID used for the current session. This value is read-only.

<session:get-creation-time>

Returns the time the current session was created. Cocoon2's way of handling this is pretty wierd, so I didn't implement it 100% to spec. This tag takes an optional parameter of 'as', which allows you to choose your date format. Your only options are "string" and "long", where the string output is a human-readable string representation (e.g. "Fri Nov 23 15:38:13 PST 2001"). "long", contrary to what you would expect, is the number of seconds since epoch. The Cocoon2 spec makes "long" the default, while mine specifies "string" as default.

<session:get-last-accessed-time>

Similar to :get-creation-time, except it returns the time since this session was last accessed (duh).

<session:remove-attribute>

Removes an attribute from the session object. Accepts either an attribute or child node called 'name' which indicates which session attribute to remove.

<session:invalidate>

Invalidates, or permanently removes, the current session from the datastore. Not all Apache::Session implementations support this, but it works just beautifully under Apache::Session::File (which is what I used for my testing).

Unsupported Tags

The following is a list of Cocoon2 Session taglib tags that I do not support in this implementation.

<session:is-new>

The Cocoon2 documentation describes this as "Indicates whether this session was just created." This parameter is a part of the J2SE Servlet specification, but is not provided AFAIK by Apache::Session. To implement this would involve putting in some strange "magic" value in the session object, and that didn't sit well with me. I'll probably implement this in the next version however.

<session:get-creation-time>, <session:get-last-accessed-time>

I don't support the "node" "as" attribute type, which is supposed to output something similar to this:

<session:creation-time>1006558479</session:creation-time>

<session:get-max-inactive-interval>, <session:set-max-inactive-interval>

This is described in Cocoon2 as:

Gets the minimum time, in seconds, that the server will maintain this session between client requests.

I am not aware of any built-in Apache::Session support for this, but it could be usefull to implement this in the future.

<xsp:page>

Under the Cocoon2 taglib, you can enable support for automatically creating sessions on-demand by putting 'create-session="true"' in the <xsp:page> node, like:

<xsp:page language="Perl" xmlns:xsp="http://apache.org/xsp/core/v1"
  xmlns:session="http://www.apache.org/1999/XSP/Session"
  create-session="true">

This would be <really> neat to have support for, but I couldn't figure out how to do this in AxKit. Maybe the next release?

EXAMPLE

<session:invalidate/>
SessionID: <xsp:expr><session:get-id/></xsp:expr>
Creation Time: <xsp:expr><session:get-creation-time/></xsp:expr>
  (Unix Epoch) <xsp:expr><session:get-creation-time as="long"/></xsp:expr>
<session:set-attribute name="foo" value="bar"/>
<session:set-attribute name="baz">
  <session:value>boo</session:value>
</session:set-attribute>
<session:set-attribute>
  <session:name>baa</session:name>
  <session:value>bob</session:value>
</session:set-attribute>
<session:remove-attribute name="foo"/>

ERRORS

To tell you the truth, I haven't tested this enough to know what happens when it fails. I'll update this if any glaring problems are found.

AUTHOR

Michael A Nachbaur, mike@nachbaur.com

COPYRIGHT

Copyright (c) 2001 Michael A Nachbaur. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

AxKit, Apache::Session, Cocoon2 Session Taglib (http://xml.apache.org/cocoon2/userdocs/xsp/session.html)