Apache::Session(3pm)

1Session(3)            User Contributed Perl Documentation           Session(3)
2
3
4

NAME

6       Apache::Session - A persistence framework for session data
7

SYNOPSIS

9         use Apache::Session::MySQL;
10
11         my %session;
12
13         #make a fresh session for a first-time visitor
14         tie %session, 'Apache::Session::MySQL';
15
16         #stick some stuff in it
17         $session{visa_number} = "1234 5678 9876 5432";
18
19         #get the session id for later use
20         my $id = $session{_session_id};
21
22         #...time passes...
23
24         #get the session data back out again during some other request
25         my %session;
26         tie %session, 'Apache::Session::MySQL', $id;
27
28         validate($session{visa_number});
29
30         #delete a session from the object store permanently
31         tied(%session)->delete;
32

DESCRIPTION

34       Apache::Session is a persistence framework which is particularly useful
35       for tracking session data between httpd requests.  Apache::Session is
36       designed to work with Apache and mod_perl, but it should work under CGI
37       and other web servers, and it also works outside of a web server
38       altogether.
39
40       Apache::Session consists of five components: the interface, the object
41       store, the lock manager, the ID generator, and the serializer.  The
42       interface is defined in Session.pm, which is meant to be easily
43       subclassed.  The object store can be the filesystem, a Berkeley DB, a
44       MySQL DB, an Oracle DB, a Postgres DB, Sybase, or Informix. Locking is
45       done by lock files, semaphores, or the locking capabilities of the
46       various databases.  Serialization is done via Storable, and optionally
47       ASCII-fied via MIME or pack().  ID numbers are generated via MD5.  The
48       reader is encouraged to extend these capabilities to meet his own
49       requirements.
50
51       A derived class of Apache::Session is used to tie together the three
52       following components.  The derived class inherits the interface from
53       Apache::Session, and specifies which store and locker classes to use.
54       Apache::Session::MySQL, for instance, uses the MySQL storage class and
55       also the MySQL locking class. You can easily plug in your own object
56       store or locker class.
57

INTERFACE

59       The interface to Apache::Session is very simple: tie a hash to the
60       desired class and use the hash as normal.  The constructor takes two
61       optional arguments.  The first argument is the desired session ID
62       number, or undef for a new session.  The second argument is a hash of
63       options that will be passed to the object store and locker classes.
64
65   tieing the session
66       Get a new session using DBI:
67
68        tie %session, 'Apache::Session::MySQL', undef,
69           { DataSource => 'dbi:mysql:sessions' };
70
71       Restore an old session from the database:
72
73        tie %session, 'Apache::Session::MySQL', $session_id,
74           { DataSource => 'dbi:mysql:sessions' };
75
76   Storing and retrieving data to and from the session
77       Hey, how much easier could it get?
78
79        $session{first_name} = "Chuck";
80        $session{an_array_ref} = [ $one, $two, $three ];
81        $session{an_object} = new Some::Class;
82
83   Reading the session ID
84       The session ID is the only magic entry in the session object, but
85       anything beginning with an "_" is considered reserved for future use.
86
87        my $id = $session{_session_id};
88
89   Permanently removing the session from storage
90        tied(%session)->delete;
91

BEHAVIOR

93       Apache::Session tries to behave the way the author believes that you
94       would expect.  When you create a new session, Session immediately saves
95       the session to the data store, or calls die() if it cannot.  It also
96       obtains an exclusive lock on the session object.  If you retrieve an
97       existing session, Session immediately restores the object from storage,
98       or calls die() in case of an error.  Session also obtains a non-
99       exclusive lock on the session.
100
101       As you put data into the session hash, Session squirrels it away for
102       later use.  When you untie() the session hash, or it passes out of
103       scope, Session checks to see if anything has changed. If so, Session
104       gains an exclusive lock and writes the session to the data store.  It
105       then releases any locks it has acquired.
106
107       Note that Apache::Session does only a shallow check to see if anything
108       has changed.  If nothing changes in the top level tied hash, the data
109       will not be updated in the backing store.  You are encouraged to
110       timestamp the session hash so that it is sure to be updated.
111
112       When you call the delete() method on the session object, the object is
113       immediately removed from the object store, if possible.
114
115       When Session encounters an error, it calls die().  You will probably
116       want to wrap your session logic in an eval block to trap these errors.
117

LOCKING AND TRANSACTIONS

119       By default, most Apache::Session implementations only do locking to
120       prevent data corruption.  The locking scheme does not provide
121       transactional consistency, such as you might get from a relational
122       database.  If you desire transactional consistency, you must provide
123       the Transaction argument with a true value when you tie the session
124       hash.  For example:
125
126        tie %s, 'Apache::Session::File', $id {
127           Directory     => '/tmp/sessions',
128           LockDirectory => '/var/lock/sessions',
129           Transaction   => 1
130        };
131
132       Note that the Transaction argument has no practical effect on the MySQL
133       and Postgres implementations.  The MySQL implementation only supports
134       exclusive locking, and the Postgres implementation uses the transaction
135       features of that database.
136

IMPLEMENTATION

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

STRATEGIES

143       Apache::Session is mainly designed to track user session between http
144       requests.  However, it can also be used for any situation where data
145       persistence is desirable.  For example, it could be used to share
146       global data between your httpd processes.  The following examples are
147       short mod_perl programs which demonstrate some session handling basics.
148
149   Sharing data between Apache processes
150       When you share data between Apache processes, you need to decide on a
151       session ID number ahead of time and make sure that an object with that
152       ID number is in your object store before starting your Apache.  How you
153       accomplish that is your own business.  I use the session ID "1".  Here
154       is a short program in which we use Apache::Session to store out
155       database access information.
156
157        use Apache;
158        use Apache::Session::File;
159        use DBI;
160
161        use strict;
162
163        my %global_data;
164
165        eval {
166            tie %global_data, 'Apache::Session::File', 1,
167               {Directory => '/tmp/sessiondata'};
168        };
169        if ($@) {
170           die "Global data is not accessible: $@";
171        }
172
173        my $dbh = DBI->connect($global_data{datasource},
174           $global_data{username}, $global_data{password}) || die $DBI::errstr;
175
176        undef %global_data;
177
178        #program continues...
179
180       As shown in this example, you should undef or untie your session hash
181       as soon as you are done with it.  This will free up any locks
182       associated with your process.
183
184   Tracking users with cookies
185       The choice of whether to use cookies or path info to track user IDs is
186       a rather religious topic among Apache users.  This example uses
187       cookies.  The implementation of a path info system is left as an
188       exercise for the reader.
189
190       Note that Apache::Session::Generate::ModUsertrack uses Apache's
191       mod_usertrack cookies to generate and maintain session IDs.
192
193        use Apache::Session::MySQL;
194        use Apache;
195
196        use strict;
197
198        #read in the cookie if this is an old session
199
200        my $r = Apache->request;
201        my $cookie = $r->header_in('Cookie');
202        $cookie =~ s/SESSION_ID=(\w*)/$1/;
203
204        #create a session object based on the cookie we got from the browser,
205        #or a new session if we got no cookie
206
207        my %session;
208        tie %session, 'Apache::Session::MySQL', $cookie, {
209             DataSource => 'dbi:mysql:sessions', #these arguments are
210             UserName   => 'mySQL_user',         #required when using
211             Password   => 'password',           #MySQL.pm
212             LockDataSource => 'dbi:mysql:sessions',
213             LockUserName   => 'mySQL_user',
214             LockPassword   => 'password'
215        };
216
217        #Might be a new session, so lets give them their cookie back
218
219        my $session_cookie = "SESSION_ID=$session{_session_id};";
220        $r->header_out("Set-Cookie" => $session_cookie);
221
222        #program continues...
223

LICENSE

240       Same as Perl.
241

AUTHORS

243       Jeffrey Baker <jwbaker@acm.org> is the author of Apache::Session.
244
245       Tatsuhiko Miyagawa <miyagawa@bulknews.net> is the author of
246       Generate::ModUniqueID and Generate::ModUsertrack
247
248       Erik Rantapaa <rantapaa@fanbuzz.com> found errors in both Lock::File
249       and Store::File
250
251       Bart Schaefer <schaefer@zanshin.com> notified me of a bug in
252       Lock::File.
253
254       Chris Winters <cwinters@intes.net> contributed the Sybase code.
255
256       Michael Schout <mschout@gkg.net> fixed a commit policy bug in 1.51.
257
258       Andreas J. Koenig <andreas.koenig@anima.de> contributed valuable CPAN
259       advice and also Apache::Session::Tree and Apache::Session::Counted.
260
261       Gerald Richter <richter@ecos.de> had the idea for a tied hash interface
262       and provided the initial code for it.  He also uses Apache::Session in
263       his Embperl module and is the author of Apache::Session::Embperl
264
265       Jochen Wiedmann <joe@ipsoft.de> contributed patches for bugs and
266       improved performance.
267
268       Steve Shreeve <shreeve@uci.edu> squashed a bug in 0.99.0 whereby a
269       cleared hash or deleted key failed to set the modified bit.
270
271       Peter Kaas <Peter.Kaas@lunatech.com> sent quite a bit of feedback with
272       ideas for interface improvements.
273
274       Randy Harmon <rjharmon@uptimecomputers.com> contributed the original
275       storage-independent object interface with input from:
276
277         Bavo De Ridder <bavo@ace.ulyssis.student.kuleuven.ac.be>
278         Jules Bean <jmlb2@hermes.cam.ac.uk>
279         Lincoln Stein <lstein@cshl.org>
280
281       Jamie LeTaul <jletual@kmtechnologies.com> fixed file locking on
282       Windows.
283
284       Scott McWhirter <scott@surreytech.co.uk> contributed verbose error
285       messages for file locking.
286
287       Corris Randall <corris@line6.net> gave us the option to use any table
288       name in the MySQL store.
289
290       Oliver Maul <oliver.maul@ixos.de> updated the Sybase modules
291
292       Innumerable users sent a patch for the reversed file age test in the
293       file locking module.
294
295       Langen Mike <mike.langen@tamedia.ch> contributed Informix modules.
296
297
298
299perl v5.12.0                      2008-12-20                        Session(3)