NAME

Liz::Session - Session module


SYNOPSIS

 use Liz::Session;

 $session = new Liz::Session;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::Session;


DESCRIPTION

The Liz::Session package allows for keeping variables between several different invocations of a script.


CLASS METHODS

The following methods can be called without an object specification, but as a class method such as Liz::Session->method().


new

Create a new Liz::Session object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but by the module in which it is incorporated.

Optionally allows a variable to be automatically set with the ID of the session if no ID was given initially or the ID has expired from the database. Variable names can be simple, e.g. ``session'' in which case it will be set in the caller's namespace, or fully qualified, e.g. ``Module::This::That::session''.

Input Parameters

 1 existing Liz::SQL object
 2 ID of existing session
   (default: use $ENV{'AUTOMATICSESSIONCOOKIE'})
 3 name of variable to store new session ID/object in automatically
   (default: do not store)
Output Parameters

 1 instantiated object
 2 flag: whether table was just created
Example

 $session = new Liz::Session( $hn );
 $sessionID = $session->ID;

 $session = new Liz::Session( $hn,$sessionID );
Note

If a name of a variable to store in is specified in a void context, then the object created (usually by using the automatic session cookie) will be stored in the indicated variable, instead of the ID.

Using Liz::Session in conjunction with Liz::Perl::AutomaticSessionCookie

When the Liz::Session module is used in conjunction with the automatic session cookie module of Liz::Perl, then no ID needs to be specified at any time. When a user visits the site for the first time, then no cookie informatie is know yet. At that point, a session is started with the visitor ID (an attempt at a unique ID using IP-number, proxy server and user agent information, amongst others).

When any attempt at opening a session is performed, it will be first done with the automatic session cookie (if available). If that failed, then an attempt is made using the visitor ID. If that is succesful, and a cookie is available, then the session key will be changed from the visitor ID to the cookie string (thus providing a truely unique access to the session object).

If the user does not have cookies enabled, or has refused to accept the cookie, the session will continue to be keyed to the visitor ID. Which in many cases will also work withour any problems.


update

Update the Liz::Session object in the database.

Output Parameters

 1 the object itself (handy for one-liners)


delete

Delete the Liz::Session object from the database.


clean

Clean Liz::Session entries from the database that have not been updated for 60 minutes or any other number of seconds that you may specify.

Input Parameters

 1 number of seconds since last update to NOT delete
   (default: 1 hour = 3600 seconds)


undef

Undef a variable in a Liz::Session. Can be used to remove an existing variable from the session.

Input Parameters

 1 list of variable names that need to be undefined
Output Parameters

 1 the object itself, so it can be used in one-liners
Example

 $session->undef( qw($score $tries) )->update;


CONTENT METHODS

The following methods allow changes to information that is associated with an entire session.


Get

Set the variables that were stored in the object in the variables of the caller's namespace, or any other namespace as specified previously by the Namespace. The complement of the Set method.

Input Parameters

 1..N the variable names to be obtained
      (default: all available)
Output Parameters

 1    the object itself (again)
Example

 $object->Get( qw($summary $text) );
 print "summary = $summary, text = $text\n";


Set

Set the values of the specified methods on the indicated object using variables from the caller's namespace or any other namespace as specified previously by the method Namespace. The complement of the Get method.

Input Parameters

 1..N the names of the variables to obtain the values of
Output Parameters

 1    the object itself (handy for oneliners)
Example

 print "summary = $summary, text = $text\n";
 $object->Set( qw($summary $text) );


Namespace

Set or return the namespace with which methods Get and Set will operate. This allows methods Get and Set to be used from within modules, and still be able to access variables which are in the Liz::Perl script itself.

Input Parameters

 1 new namespace to work with
   (default: no change, use caller's namespace)
Output Parameters

 1 old/current namespace to work with
Example

 $session->Namespace( 'Liz::Perl::HTML1' );
 $session->Namespace( scalar(caller()) );
 $namespace = $session->Namespace;


INTERPROCESS METHODS

The following methods are handy when using the same session between two or more processes.


WaitUntilChanged

Wait until some other process has updated the session information. The period to wait before the database is checked, is specified in as well as the maximum number of periods to wait before giving up.

Input Parameters

 1 time to wait until check is done
   (default: 1 second)
 2 number of periods to wait before giving up
   (default: 300)
Output Parameters

 1 flag: whether session was updated
   (undef = gave up or session expired)


DEBUGGING METHODS

The following methods are handy when debugging sessions.


Dump

Return a string with the listed variables and their values, or all variables. Intended for debugging purposes only.

Input Parameters

 1..N the variable names to be debugged
      (default: all available)
Output Parameters

 1    the object itself (again)
Example

 print $object->Dump;


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.45, 30 September 1999

Now no longer puts Exporter in ISA: it was not needed.

Version 0.44, 17 August 1999

Method new now calls Liz::SQL's ``new'' to create the object.

Version 0.43, 9 July 1999

Changed CREATE TABLE to new Liz::SQL 'create' method.

Version 0.42, 23 June 1999

Changed from using method ``Exists'' to ``Count'' in method new to allow for a much faster check on the existence of a table.

Version 0.41, 14 May 1999

Method delete was inherited from Liz::SQL, but that doesn't work in this special case. A new ``own'' method delete has now been added.

Version 0.40, 6 May 1999

Method new will now resort to using $ENV{'VISITORID'} if available and no $ENV{'AUTOMATICSESSIONCOOKIE'} is available. This allows users to be traced from the very first request (first keying on the almost unique VISITORID) and then, when a automatic session cookie arrives, to transfer the session data to the cookie.

Source code adapted to a more general Perl code compatible style.

Version 0.37, 28 March 1999

Fixed problem that would lose the object's ID field when AUTOLOADed method Namespace was being used. Session objects did not have the KeepID flag set yet, they do now!

Version 0.36, 27 March 1999

Fixed problem that occurred when new style cookie-session ID's were used with previously created databases. New database contains a 32 byte key, whereas the old one only contained 8 bytes. Old databases will now be automatically converted when encountered.

Version 0.35, 26 March 1999

Method Dump now prints the dump of the object when called in a void context, and aroundfixes <PRE> when done from within Liz::Perl environment.

Fixed problem in methods Get and Set that would cause them not to work if the namespace specified did not contain trailing '::'.

Added explicit support for the Namespace method, which allows specification of the namespace with which methods Get and Set operate.

Version 0.34, 25 March 1999

Now supports Liz::Perl's automatic session cookies: if an automatic session cookie is available, then that will be used as a key to store the session information with. If there is no session info yet and automatic session cookies are used, then a new session with the automatic session cookie will be created.

Version 0.33, 6 November 1998

Added undef method for removing variables from the session object, and after an update, from the database.

Version 0.32, 9 October 1998

Now '&' is correctly encoded prior to storage. Because values are stored in 'ampersand separated' format, this prevents errors.

Version 0.31, 6 October 1998

Reduced memory footprint by using fully qualified global variables and external subroutines.

Method delete is now AUTOLOADed.

Version 0.3, 6 July 1998

Method new now allows specification of variable in which to automatically store the session ID.

Version 0.21, 14 June 1998

Method update now also returns the object itself.

Version 0.2, 14 June 1998

Internally replaced the NAMES array with a NAMES hash so that duplicate keys cannot occur anymore. This also gets rid of an expensive grep() that somehow didn't work.

Version 0.1, 12 June 1998

First version of this true Perl module.