1Session(3) User Contributed Perl Documentation Session(3)
2
3
4
6 Apache::Session - A persistence framework for session data
7
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
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 alto‐
38 gether.
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 sub‐
43 classed. 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 var‐
46 ious 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 components. The derived class inherits the interface from Apache::Ses‐
53 sion, 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
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 num‐
62 ber, 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
67 Get a new session using DBI:
68
69 tie %session, 'Apache::Session::MySQL', undef,
70 { DataSource => 'dbi:mysql:sessions' };
71
72 Restore an old session from the database:
73
74 tie %session, 'Apache::Session::MySQL', $session_id,
75 { DataSource => 'dbi:mysql:sessions' };
76
77 Storing and retrieving data to and from the session
78
79 Hey, how much easier could it get?
80
81 $session{first_name} = "Chuck";
82 $session{an_array_ref} = [ $one, $two, $three ];
83 $session{an_object} = new Some::Class;
84
85 Reading the session ID
86
87 The session ID is the only magic entry in the session object, but any‐
88 thing beginning with a "_" is considered reserved for future use.
89
90 my $id = $session{_session_id};
91
92 Permanently removing the session from storage
93
94 tied(%session)->delete;
95
97 Apache::Session tries to behave the way the author believes that you
98 would expect. When you create a new session, Session immediately saves
99 the session to the data store, or calls die() if it cannot. It also
100 obtains an exclusive lock on the session object. If you retrieve an
101 existing session, Session immediately restores the object from storage,
102 or calls die() in case of an error. Session also obtains an non-exclu‐
103 sive lock on the session.
104
105 As you put data into the session hash, Session squirrels it away for
106 later use. When you untie() the session hash, or it passes out of
107 scope, Session checks to see if anything has changed. If so, Session
108 gains an exclusive lock and writes the session to the data store. It
109 then releases any locks it has acquired.
110
111 Note that Apache::Session does only a shallow check to see if anything
112 has changed. If nothing changes in the top level tied hash, the data
113 will not be updated in the backing store. You are encouraged to time‐
114 stamp the session hash so that it is sure to be updated.
115
116 When you call the delete() method on the session object, the object is
117 immediately removed from the object store, if possible.
118
119 When Session encounters an error, it calls die(). You will probably
120 want to wrap your session logic in an eval block to trap these errors.
121
123 By default, most Apache::Session implementations only do locking to
124 prevent data corruption. The locking scheme does not provide transac‐
125 tional consistency, such as you might get from a relational database.
126 If you desire transactional consistency, you must provide the Transac‐
127 tion argument with a true value when you tie the session hash. For
128 example:
129
130 tie %s, 'Apache::Session::File', $id {
131 Directory => '/tmp/sessions',
132 LockDirectory => '/var/lock/sessions',
133 Transaction => 1
134 };
135
136 Note that the Transaction argument has no practical effect on the MySQL
137 and Postgres implementations. The MySQL implementation only supports
138 exclusive locking, and the Postgres implementation uses the transaction
139 features of that database.
140
142 The way you implement Apache::Session depends on what you are trying to
143 accomplish. Here are some hints on which classes to use in what situa‐
144 tions
145
147 Apache::Session is mainly designed to track user session between http
148 requests. However, it can also be used for any situation where data
149 persistence is desirable. For example, it could be used to share
150 global data between your httpd processes. The following examples are
151 short mod_perl programs which demonstrate some session handling basics.
152
153 Sharing data between Apache processes
154
155 When you share data between Apache processes, you need to decide on a
156 session ID number ahead of time and make sure that an object with that
157 ID number is in your object store before starting you Apache. How you
158 accomplish that is your own business. I use the session ID "1". Here
159 is a short program in which we use Apache::Session to store out data‐
160 base access information.
161
162 use Apache;
163 use Apache::Session::File;
164 use DBI;
165
166 use strict;
167
168 my %global_data;
169
170 eval {
171 tie %global_data, 'Apache::Session::File', 1,
172 {Directory => '/tmp/sessiondata'};
173 };
174 if ($@) {
175 die "Global data is not accessible: $@";
176 }
177
178 my $dbh = DBI->connect($global_data{datasource},
179 $global_data{username}, $global_data{password}) ⎪⎪ die $DBI::errstr;
180
181 undef %global_data;
182
183 #program continues...
184
185 As shown in this example, you should undef or untie your session hash
186 as soon as you are done with it. This will free up any locks associ‐
187 ated with your process.
188
189 Tracking users with cookies
190
191 The choice of whether to use cookies or path info to track user IDs is
192 a rather religious topic among Apache users. This example uses cook‐
193 ies. The implementation of a path info system is left as an exercise
194 for the reader.
195
196 Note that Apache::Session::Generate::ModUsertrack uses Apache's
197 mod_usertrack cookies to generate and maintain session IDs.
198
199 use Apache::Session::MySQL;
200 use Apache;
201
202 use strict;
203
204 #read in the cookie if this is an old session
205
206 my $r = Apache->request;
207 my $cookie = $r->header_in('Cookie');
208 $cookie =~ s/SESSION_ID=(\w*)/$1/;
209
210 #create a session object based on the cookie we got from the browser,
211 #or a new session if we got no cookie
212
213 my %session;
214 tie %session, 'Apache::Session::MySQL', $cookie, {
215 DataSource => 'dbi:mysql:sessions', #these arguments are
216 UserName => 'mySQL_user', #required when using
217 Password => 'password', #MySQL.pm
218 LockDataSource => 'dbi:mysql:sessions',
219 LockUserName => 'mySQL_user',
220 LockPassword => 'password'
221 };
222
223 #Might be a new session, so lets give them their cookie back
224
225 my $session_cookie = "SESSION_ID=$session{_session_id};";
226 $r->header_out("Set-Cookie" => $session_cookie);
227
228 #program continues...
229
231 Apache::Session::MySQL, Apache::Session::Postgres, Apache::Ses‐
232 sion::File, Apache::Session::DB_File, Apache::Session::Oracle,
233 Apache::Session::Sybase
234
235 The O Reilly book "Apache Modules in Perl and C", by Doug MacEachern
236 and Lincoln Stein, has a chapter on keeping state.
237
239 Jeffrey Baker <jwbaker@acm.org> is the author of Apache::Session.
240
241 Tatsuhiko Miyagawa <miyagawa@bulknews.net> is the author of Gener‐
242 ate::ModUniqueID and Generate::ModUsertrack
243
244 Erik Rantapaa <rantapaa@fanbuzz.com> found errors in both Lock::File
245 and Store::File
246
247 Bart Schaefer <schaefer@zanshin.com> notified me of a bug in
248 Lock::File.
249
250 Chris Winters <cwinters@intes.net> contributed the Sybase code.
251
252 Michael Schout <mschout@gkg.net> fixed a commit policy bug in 1.51.
253
254 Andreas J. Koenig <andreas.koenig@anima.de> contributed valuable CPAN
255 advice and also Apache::Session::Tree and Apache::Session::Counted.
256
257 Gerald Richter <richter@ecos.de> had the idea for a tied hash interface
258 and provided the initial code for it. He also uses Apache::Session in
259 his Embperl module and is the author of Apache::Session::Embperl
260
261 Jochen Wiedmann <joe@ipsoft.de> contributed patches for bugs and
262 improved performance.
263
264 Steve Shreeve <shreeve@uci.edu> squashed a bug in 0.99.0 whereby a
265 cleared hash or deleted key failed to set the modified bit.
266
267 Peter Kaas <Peter.Kaas@lunatech.com> sent quite a bit of feedback with
268 ideas for interface improvements.
269
270 Randy Harmon <rjharmon@uptimecomputers.com> contributed the original
271 storage-independent object interface with input from:
272
273 Bavo De Ridder <bavo@ace.ulyssis.student.kuleuven.ac.be>
274 Jules Bean <jmlb2@hermes.cam.ac.uk>
275 Lincoln Stein <lstein@cshl.org>
276
277 Jamie LeTaul <jletual@kmtechnologies.com> fixed file locking on Win‐
278 dows.
279
280 Scott McWhirter <scott@surreytech.co.uk> contributed verbose error mes‐
281 sages for file locking.
282
283 Corris Randall <corris@line6.net> gave us the option to use any table
284 name in the MySQL store.
285
286 Oliver Maul <oliver.maul@ixos.de> updated the Sybase modules
287
288 Innumerable users sent a patch for the reversed file age test in the
289 file locking module.
290
291 Langen Mike <mike.langen@tamedia.ch> contributed Informix modules.
292
293
294
295perl v5.8.8 2004-02-24 Session(3)