view release on metacpan or  search on metacpan

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

=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
      UserName   => 'mySQL_user',         #required when using
      Password   => 'password',           #MySQL.pm
      LockDataSource => 'dbi:mysql:sessions',
      LockUserName   => 'mySQL_user',
      LockPassword   => 'password'
 };

 #Might be a new session, so lets give them their cookie back

 my $session_cookie = "SESSION_ID=$session{_session_id};";
 $r->header_out("Set-Cookie" => $session_cookie);

 #program continues...

=head1 SEE ALSO

Apache::Session::MySQL, Apache::Session::Postgres, Apache::Session::File,
Apache::Session::DB_File, Apache::Session::Oracle, Apache::Session::Sybase

The O Reilly book "Apache Modules in Perl and C", by Doug MacEachern and
Lincoln Stein, has a chapter on keeping state.

CGI::Session uses OO interface to do same thing. It is better maintained,
but less possibilies.

Catalyst::Plugin::Session - support of sessions in Catalyst

Session - OO interface to Apache::Session

=head1 LICENSE

Under the same terms as Perl itself.

=head1 AUTHORS

Alexandr Ciornii, L<http://chorny.net> - current maintainer

Jeffrey Baker <jwbaker@acm.org> is the author of 
Apache::Session.

Tatsuhiko Miyagawa <miyagawa@bulknews.net> is the author of 
Generate::ModUniqueID and Generate::ModUsertrack

Erik Rantapaa <rantapaa@fanbuzz.com> found errors in both Lock::File
and Store::File

Bart Schaefer <schaefer@zanshin.com> notified me of a bug in 
Lock::File.

Chris Winters <cwinters@intes.net> contributed the Sybase code.

Michael Schout <mschout@gkg.net> fixed a commit policy bug in 1.51.

Andreas J. Koenig <andreas.koenig@anima.de> contributed valuable CPAN
advice and also Apache::Session::Tree and Apache::Session::Counted.

Gerald Richter <richter@ecos.de> had the idea for a tied hash interface
and provided the initial code for it.  He also uses Apache::Session in
his Embperl module and is the author of Apache::Session::Embperl

Jochen Wiedmann <joe@ipsoft.de> contributed patches for bugs and
improved performance.

Steve Shreeve <shreeve@uci.edu> squashed a bug in 0.99.0 whereby
a cleared hash or deleted key failed to set the modified bit.