Liz::Session - Session module
use Liz::Session;
$session = new Liz::Session;
#!/usr/local/bin/perl
use Liz::Session;
The Liz::Session package allows for keeping variables between several different invocations of a script.
The following methods can be called without an object specification, but as a class method such as Liz::Session->method().
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''.
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)
1 instantiated object 2 flag: whether table was just created
$session = new Liz::Session( $hn ); $sessionID = $session->ID;
$session = new Liz::Session( $hn,$sessionID );
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.
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 the Liz::Session object in the database.
1 the object itself (handy for one-liners)
Delete the Liz::Session object from the database.
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.
1 number of seconds since last update to NOT delete (default: 1 hour = 3600 seconds)
Undef a variable in a Liz::Session. Can be used to remove an existing variable from the session.
1 list of variable names that need to be undefined
1 the object itself, so it can be used in one-liners
$session->undef( qw($score $tries) )->update;
The following methods allow changes to information that is associated with an entire session.
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.
1..N the variable names to be obtained
(default: all available)
1 the object itself (again)
$object->Get( qw($summary $text) ); print "summary = $summary, text = $text\n";
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.
1..N the names of the variables to obtain the values of
1 the object itself (handy for oneliners)
print "summary = $summary, text = $text\n"; $object->Set( qw($summary $text) );
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.
1 new namespace to work with (default: no change, use caller's namespace)
1 old/current namespace to work with
$session->Namespace( 'Liz::Perl::HTML1' ); $session->Namespace( scalar(caller()) ); $namespace = $session->Namespace;
The following methods are handy when using the same session between two or more processes.
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.
1 time to wait until check is done (default: 1 second) 2 number of periods to wait before giving up (default: 300)
1 flag: whether session was updated (undef = gave up or session expired)
The following methods are handy when debugging sessions.
Return a string with the listed variables and their values, or all variables. Intended for debugging purposes only.
1..N the variable names to be debugged
(default: all available)
1 the object itself (again)
print $object->Dump;
Elizabeth Mattijsen ( lizperl@INC.nl )
(C) 1998-1999 International Network Consultants
Now no longer puts Exporter in ISA: it was not needed.
Method new now calls Liz::SQL's ``new'' to create the object.
Changed CREATE TABLE to new Liz::SQL 'create' method.
Changed from using method ``Exists'' to ``Count'' in method new to allow for a much faster check on the existence of a table.
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.
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.
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!
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.
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.
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.
Added undef method for removing variables from the session object, and after an update, from the database.
Now '&' is correctly encoded prior to storage. Because values are stored in 'ampersand separated' format, this prevents errors.
Reduced memory footprint by using fully qualified global variables and external subroutines.
Method delete is now AUTOLOADed.
Method new now allows specification of variable in which to automatically store the session ID.
Method update now also returns the object itself.
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.
First version of this true Perl module.