view release on metacpan or  search on metacpan

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

=item 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)

=item 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.

=item counter

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

=item 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.

=item 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.

=back

As with other modules in the Apache::Session collection, the tied hash
contains a key C<_session_id>. You must be aware that the value of this
hash entry is not the same as the one you passed in when you retrieved
the session (if you retrieved a session at all). So you have to make
sure that you send your users a new session-id in each response, and
that this is never 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 or three parts:
an optional host alias given by the HostID paramter, followed by a
colon. Then an ordinary number which is a simple counter which is
followed by an underscore. And finally a session-ID like the one in
Apache::Session. The number part is used as an identifier of the
session and the ID part is used as a password. The number part is
easily predictable, but the second part is reasonable unpredictable.
We use the first part for implementation details like storage on the
disk and the second part to verify the ownership of that token.

=head1 PREREQUISITES

Apache::Session::Counted needs Apache::Session and File::CounterFile,
all available from the CPAN. The HostID and HostURL parameters for a
cluster solution need LWP installed.

=head1 EXAMPLES

The following example resets the counter every 24 hours and keeps the
totals of every day as a side effect:

  my(@t) = localtime;
  tie %session, 'Apache::Session::Counted', $sid,
  {
   Directory => ...,
   DirLevels => ...,
   CounterFile => sprintf("/some/dir/%04d-%02d-%02d", $t[5]+1900,$t[4]+1,$t[3])
  };


The same effect can be accomplished with a fixed filename and an
external cronjob that resets the counter like so:

  use File::CounterFile;
  $c=File::CounterFile->new("/usr/local/apache/data/perl/sessiondemo/counter");
  $c->lock;
  $c-- while $c>0;
  $c->unlock;


=head1 AUTHOR

Andreas Koenig <andreas.koenig@anima.de>

=head1 COPYRIGHT

This software is copyright(c) 1999-2002 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.

=cut