MAN page from Old RedHat 6.X perl-HTML-EP-0.2010-6.i386.rpm

lib::HTML::EP::Session

Section: User Contributed Perl Documentation (3)
Updated: perl 5.005, patch 03
Index

NAME

  HTML::EP::Session - Session management for the HTML::EP package

SYNOPSIS

  <ep-comment>    Create a new session or open an existing session  </ep-comment>  <ep-session id="$cgi->id$" var="cart">

  <ep-comment>    Modify the session by putting an item into the shopping cart  </ep-comment>  <ep-perl>    my $_ = $self; my $cart = $self->{'cart'};    my $items = $cart->{'items'} || {};    my $cgi = $self->{'cgi'};    $items->{$cgi->param('item_id')} = $cgi->param('num_items');  </ep-perl>

  <ep-comment>    Same thing by using the ep-item command  </ep-comment>  <ep-session-item item="$cgi->item_id"   num="$cgi->num_items">

  <ep-comment>    Store the session  </ep-comment>  <ep-session-store>

DESCRIPTION

The HTML::EP::Session package is something like a little brother ofApache::Session: Given an ID and a structured Perl variable calledthe session, it stores the session into a DBI database, an externalfile or whatever you prefer. For example you like to use this inshopping carts: The shopping cart could look like this

  $session = {    'id' => '21A32DE61A092DA1',    'items' => { '10043-A' => 1, # 1 item of article '10043-A'                 '10211-C' => 2  # 2 items of article '10211-C'               }  }

The package takes the session, converts it into a string representation byusing the Storable or FreezeThaw module and saves it into somenon-volatile storage space. The storage method is choosen by selectingan appropriate subclass of HTML::EP::Session, for exampleHTML::EP::Session::DBI, the default class using DBI, the databaseindependent Perl interface or HTML::EP::Session::File for using flatfiles.

Creating or opening a session

  <ep-session class="HTML::EP::Session::DBI" table="sessions"              var=session id="$@cgi->id$" hex=0>

If the attribute id is empty or not set, this will create a new andempty session for you. Otherwise the existing session with the givenid will be opened.

By default the session will have class HTML::EP::Session::DBIand data will be stored in the table sessions, but you canchoose another subclass of HTML::EP::Session for saving data.The session is stored in the session variable of the object, butthat is overridable with the var attribute.

Some storage systems don't support NUL bytes. The hex attributeforces conversion of session strings into hex strings, if set to on.The default is off.

Some session classes, in particular the DBI session class, willgenerate an ID for you, if required. That ID can by retrievedby looking at

        $self->{'_ep_session_id'}

or, within an HTML page with

        $_ep_session_id$

Storing the session

  <ep-session-store locked=0>

This stores the session back into the non-volatile storage. By defaultthe session is unlocked at the same time and must not be modified inwhat follows, unless you set the optional locked attribute to atrue value.

Managing a shopping cart

As a helper for shopping carts you might use the following command:

  <ep-session-item item="$cgi->item$" num="$cgi->num$">

This command uses a hash ref items in the shopping cart, the hashwill be created automatically. The value num is stored in the hashskey item. Alternatively you might use

  <ep-session-item item="$cgi->item$" add="$cgi->num$">

which is very much the same, but the item is incremented by add.

Deleting a session

You can delete an existing session with

  <ep-session-delete>

LOCKING CONSIDERATIONS

All subclasses have to implement a locking scheme. To keep this schemeclean and simple, the following rules must be applied:

1.): First of all, acquire the resources that the respective subclass needs.In the case of the DBI subclass this means that you have to execute theep-database command.
2.): Next you create or open the session.
3.): If required, do any modifications and call ep-session-store orep-session-delete.
4.): Once you have called ep-session-store or ep-session-delete, youmost not use any more ep-session commands.

SUBCLASS INTERFACE

Subclasses of HTML::EP::Session must implement the following methods:

new($ep, $id, \%attr): (Class method) This constructor creates a new session with id $id.The constructor should configure itself by using the EP object $epand the attribute hash ref \%attr.
Open($ep, $id, \%attr): (Class method) This constructor must open an existing session.
Store($ep, $id, $locked): (Instance method) Stores the session. The $locked argument advicesto keep the session locked (TRUE) or unlocked (FALSE).
Delete($ep, $id)

Error handling in subclasses is simple: All you need to do is throwinga Perl exception. If subclasses need to maintain own data, they shouldstore it in $ep->{'_ep_session_data'}. The id is stored in$ep->{'_ep_session_id'}.

The DBI subclass

This class is using the DBI (Database independent Perl interface), sessionsare stored in a table. The table name is given by the table attributeand defaults to sessions. The table structure is like

  CREATE TABLE SESSIONS (      ID INTEGER NOT NULL PRIMARY KEY,      SESSION LONGVARCHAR,      ACCESSED TIMESTAMP,      LOCKED INTEGER  )

in particular the SESSION column must be sufficiently large. I suggestusing something like up to 65535, for example I am using SHORT BLOBwith MySQL.

The SESSION column must accept binary characters, in particular NUL bytes.If it doesn't, you need to replace the Storable package with FreezeThaw.the Storable(3) manpage. the FreezeThaw(3) manpage.

Ilya Ketris (ilyaAATTgde.to) has pointed out, that these column names arecausing problems from time to time. He suggested to use queries like

  INSERT INTO $table ("ID", "SESSION", ...

instead. This is of course higly incompatible to other engines. To fixthat problem, I have added a subclass of HTML::EP::Session::DBI,called HTML::EP::Session::DBIq (quoted). You use it by just replacingthe class name in the ep-session statement.

The Cookie subclass

This class is using Cookies, as introduced by Netscape 2. When usingCookies for the session, you have to use a slightly different syntax:

  <ep-session class="HTML::EP::Session::Cookie" id="sessions"              var=session id="$@cgi->id$" expires="+1h"              domain="www.company.com" path="/"              zlib=0 base64=0>

The attribute id is the cookie's name. (Cookies are name/valuepairs.) The optional attributes expires, domain and pathare referring to the respective attributes of CG::Cookie->new().the CGI::Cookie(3) manpage.

Cookies are unfortunately restricted to a certain size, about 4096bytes. If your session is getting too large, you might try to reducethe cookie size by using the Compress::Zlib and/or MIME::Base64module. This is enabled by adding the parameters zlib=1 and/orbase64=1.

The Dumper subclass

This is, in some sense, an unusual class for sessions: All usersare sharing a single session, unlike the DBI and Cookie subclasses,which implement one session per user. I enjoy using the Dumpersubclass anyways, for example to implement site wide preferences.

What the class does is creating a file which holds a singlehash ref. This hash ref is created using the Data::Dumperpackage. the Data::Dumper(3) manpage.

You create a Dumper session like this:

  <ep-session class="HTML::EP::Session::Dumper"              id="/var/tmp/my.session" var="prefs">

In other words, the session ID is just the name of the file.

MULTIPLE SESSION

When looking at the Cookie and Dumper subclass, the question arises:Can I use multiple sessions within a single HTML page? Of course youcan!

However, there are a few drawbacks:

1.): The variable $_ep_session_id$ always contains the ID of thelast created session. After you have created the firstsession, it will contains this sessions ID. If you createanother session, the variable will change to the new ID.
2.): You must use the attributes var=something and id=somethingwith any call to ep-session, ep-session-store, ep-session-deleteand ep-session-item.

AUTHOR AND COPYRIGHT

This module is

    Copyright (C) 1998    Jochen Wiedmann                          Am Eisteich 9                          72555 Metzingen                          Germany

                          Phone: +49 7123 14887                          Email: joeAATTispsoft.de

You may distribute this module under the terms of eitherthe GNU General Public License or the Artistic License, asspecified in the Perl README file.

This document was created byman2html,using the manual pages.