view release on metacpan or  search on metacpan

lib/Apache/Session.pm  view on Meta::CPAN

you would expect.  When you create a new session, Session immediately
saves the session to the data store, or calls die() if it cannot.  It
also obtains an exclusive lock on the session object.  If you retrieve
an existing session, Session immediately restores the object from storage,
or calls die() in case of an error.  Session also obtains a non-exclusive
lock on the session.

As you put data into the session hash, Session squirrels it away for
later use.  When you untie() the session hash, or it passes out of
scope, Session checks to see if anything has changed. If so, Session 
gains an exclusive lock and writes the session to the data store.  
It then releases any locks it has acquired.  

Note that Apache::Session does only a shallow check to see if anything has
changed.  If nothing changes in the top level tied hash, the data will not be
updated in the backing store.  You are encouraged to timestamp the session hash
so that it is sure to be updated.

When you call the delete() method on the session object, the
object is immediately removed from the object store, if possible.

When Session encounters an error, it calls die().  You will probably 
want to wrap your session logic in an eval block to trap these errors.

=head1 LOCKING AND TRANSACTIONS

By default, most Apache::Session implementations only do locking to prevent
data corruption.  The locking scheme does not provide transactional
consistency, such as you might get from a relational database.  If you desire
transactional consistency, you must provide the Transaction argument with a
true value when you tie the session hash.  For example:

 tie %s, 'Apache::Session::File', $id {
    Directory     => '/tmp/sessions',
    LockDirectory => '/var/lock/sessions',
    Transaction   => 1
 };

Note that the Transaction argument has no practical effect on the MySQL and
Postgres implementations.  The MySQL implementation only supports exclusive
locking, and the Postgres implementation uses the transaction features of that
database.

=head1 IMPLEMENTATION

The way you implement Apache::Session depends on what you are
trying to accomplish.  Here are some hints on which classes to
use in what situations

=head1 STRATEGIES

Apache::Session is mainly designed to track user session between 
http requests.  However, it can also be used for any situation
where data persistence is desirable.  For example, it could be
used to share global data between your httpd processes.  The 
following examples are short mod_perl programs which demonstrate
some session handling basics.

=head2 Sharing data between Apache processes

When you share data between Apache processes, you need to decide on a
session ID number ahead of time and make sure that an object with that
ID number is in your object store before starting your Apache.  How you
accomplish that is your own business.  I use the session ID "1".  Here
is a short program in which we use Apache::Session to store out 
database access information.

 use Apache;
 use Apache::Session::File;
 use DBI;

 use strict;

 my %global_data;

 eval {
     tie %global_data, 'Apache::Session::File', 1,
        {Directory => '/tmp/sessiondata'};
 };
 if ($@) {
    die "Global data is not accessible: $@";
 }

 my $dbh = DBI->connect($global_data{datasource}, 
    $global_data{username}, $global_data{password}) || die $DBI::errstr;

 undef %global_data;

 #program continues...

As shown in this example, you should undef or untie your session hash
as soon as you are done with it.  This will free up any locks associated
with your process.

=head2 Tracking users with cookies

The choice of whether to use cookies or path info to track user IDs 
is a rather religious topic among Apache users.  This example uses cookies.
The implementation of a path info system is left as an exercise for the
reader.

Note that Apache::Session::Generate::ModUsertrack uses Apache's mod_usertrack
cookies to generate and maintain session IDs.

 use Apache::Session::MySQL;
 use Apache;

 use strict;

 #read in the cookie if this is an old session

 my $r = Apache->request;
 my $cookie = $r->header_in('Cookie');
 $cookie =~ s/SESSION_ID=(\w*)/$1/;

 #create a session object based on the cookie we got from the browser,
 #or a new session if we got no cookie

 my %session;
 tie %session, 'Apache::Session::MySQL', $cookie, {
      DataSource => 'dbi:mysql:sessions', #these arguments are