NAME

Apache::Session::Counted - Session management via a File::CounterFile

SYNOPSYS

tie %s, 'Apache::Session::Counted', $sessionid, {
                               Directory => <root of directory tree>,
                               DirLevels => <number of dirlevels>,
                               CounterFile => <filename for File::CounterFile>,
                               AlwaysSave => <boolean>
                                                }

DESCRIPTION

This session module is based on Apache::Session, but it persues a different notion of a session, so you probably have to adjust your expectations a little.

A session in this module only lasts from one request to the next. At that point a new session starts. Data are not lost though, the only thing that is lost from one request to the next is the session-ID. So the only things you have to treat differently than in Apache::Session are those parts that rely on the session-ID as a fixed token per user. Everything else remains the same. See below for a discussion what this model buys you.

The usage of the module is via a tie as described in the synopsis. The arguments have the following meaning:

Directory, DirLevels

Compare the desription in Apache::Session::TreeStore.

CounterFile

A filename to be used by the File::CounterFile module. By changing that file or the filename periodically, you can achieve arbitrary patterns of key generation.

AlwaysSave

A boolean which, if true, forces storing of session data in any case. If false, only a STORE, DELETE or CLEAR trigger that the session file will be written when the tied hash goes out of scope. This has the advantage that you can retrieve an old session without storing its state again.

What this model buys you

storing state selectively

You need not store session data for each and every request of a particular user. There are so many CGI requests that can easily be handled with two hidden fields and do not need any session support on the server side, and there are others where you definitely need session support. Both can appear within the same application. Apache::Session::Counted allows you to switch session writing on and off during your application without effort. (In fact, this advantage is shared with the clean persistence model of Apache::Session)

keeping track of transactions

As each request of a single user remains stored until you restart the counter, there are all previous states of a single session close at hand. The user presses the back button 5 times and changes a decision and simply opens a new branch of the same session. This can be an advantage and a disadvantage. I tend to see it as a very strong feature. Your milage may vary.

counter

You get a counter for free which you can control just like File::CounterFile (because it is File::CounterFile).

cleanup

Your data storage area cleans up itself automatically. Whenever you reset your counter via File::CounterFile, the storage area in use is being reused. Old files are being overwritten in the same order they were written, giving you a lot of flexibility to control session storage time and session storage disk space.

performance

The notion of daisy-chained sessions simplifies the code of the session handler itself quite a bit and it is likely that this simplification results in an improved performance (not tested yet due to lack of benchmarking apps for sessions). There are less file stats and less sections that need locking, but without real world figures, it's hard to tell what's up.

As with other modules in the Apache::Session collection, the tied hash contains a key <_session_id>. You must be aware that the value of this hash entry is not the same as the one you passed in. So make sure that you send your users a new session-id in each response, not the old one.

As an implemenation detail it may be of interest to you, that the session ID in Apache::Session::Counted consists of two parts: an ordinary number which is a simple counter and a session-ID like the one in Apache::Session. The two parts are concatenated by an underscore. The first part is used as an identifier of the session and the second part is used as a one-time password. The first part is easily predictable, but the second part is as unpredictable as Apache::Session's session ID. We use the first part for implementation details like storage on the disk and the second part to verify the ownership of that token.

PREREQUISITES

Apache::Session::Counted needs Apache::Session, Apache::Session::TreeStore, and File::CounterFile, all available from the CPAN.

EXAMPLES

XXX Two examples should show the usage of a date string and the usage of an external cronjob to influence counter and cleanup.

AUTHOR

Andreas Koenig <andreas.koenig@anima.de>

COPYRIGHT

This software is copyright(c) 1999 Andreas Koenig. It is free software and can be used under the same terms as perl, i.e. either the GNU Public Licence or the Artistic License.