data/TWiki/CGISessionDriverDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 head	1.1;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.1
     9 date	2008.01.22.03.21.33;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	;
    12 
    13 
    14 desc
    15 @buildrelease
    16 @
    17 
    18 
    19 1.1
    20 log
    21 @buildrelease
    22 @
    23 text
    24 @---+ Package ==
    25 *extends* <tt>CGI::Session::ErrorHandler</tt>
    26 
    27 
    28 %TOC%
    29 =head1 NAME
    30 
    31 CGI::Session::Driver - CGI::Session driver specifications
    32 
    33 =head1 WARNING
    34 
    35 Version 4.0 of CGI::Session's driver specification is B<NOT> backward compatible with previous specification. If you already have a driver developed to work with the previous version you're highly encouraged to upgrade your driver code to make it compatible with the current version. Fortunately, current driver specs are a lot easier to adapt to.
    36 
    37 If you need any help converting your driver to meet current specs, send me an e-mail. For support information see
    38 L<CGI::Session|CGI::Session>
    39 
    40 =head1 SYNOPSIS
    41 
    42     require CGI::Session::Driver;
    43     @@ISA = qw( CGI::Session::Driver );
    44 
    45 =head1 DESCRIPTION
    46 
    47 CGI::Session::Driver is a base class for all CGI::Session's native drivers. It also documents driver specifications for those willing to write drivers for different databases not currently supported by CGI::Session.
    48 
    49 =head1 WHAT IS A DRIVER
    50 
    51 Driver is a piece of code that helps CGI::Session library to talk to specific database engines, or storage mechanisms. To be more precise, driver is a F<.pm> file that inherits from CGI::Session::Driver and defines L<retrieve()|/"retrieve($self, $sid)">, L<store()|/"store($self, $sid, $datastr)"> and L<remove()|/"remove($self, $sid)"> methods.
    52 
    53 =head2 BLUEPRINT
    54 
    55 The best way of learning the specs is to look at a blueprint of a driver:
    56 
    57     package CGI::Session::Driver::your_driver_name;
    58     use strict;
    59     use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
    60 
    61     sub init {
    62         my ($self) = @@_;
    63         # optional
    64     }
    65 
    66     sub DESTROY {
    67         my ($self) = @@_;
    68         # optional
    69     }
    70 
    71     sub store {
    72         my ($self, $sid, $datastr) = @@_;
    73         # Store $datastr, which is an already serialized string of data.
    74     }
    75 
    76     sub retrieve {
    77         my ($self, $sid) = @@_;
    78         # Return $datastr, which was previously stored using above store() method.
    79         # Return $datastr if $sid was found. Return 0 or "" if $sid doesn't exist
    80         }
    81 
    82     sub remove {
    83         my ($self, $sid) = @@_;
    84         # Remove storage associated with $sid. Return any true value indicating success,
    85         # or undef on failure.
    86     }
    87 
    88     sub traverse {
    89         my ($self, $coderef) = @@_;
    90         # execute $coderef for each session id passing session id as the first and the only
    91         # argument
    92     }
    93 
    94     1;
    95 
    96 All the attributes passed as the second argument to CGI::Session's new() or load() methods will automatically
    97 be made driver's object attributes. For example, if session object was initialized as following:
    98 
    99     $s = CGI::Session->new("driver:your_driver_name", undef, {Directory=>'/tmp/sessions'});
   100 
   101 You can access value of 'Directory' from within your driver like so:
   102 
   103     sub store {
   104         my ($self, $sid, $datastr) = @@_;
   105         my $dir = $self->{Directory};   # <-- in this example will be '/tmp/sessions'
   106     }
   107 
   108 Optionally, you can define C<init()> method within your driver to do driver specific global initialization. C<init()> method will be invoked only once during the lifecycle of your driver, which is the same as the lifecycle of a session object.
   109 
   110 For examples of C<init()> look into the source code of native CGI::Session drivers.
   111 
   112 =head1 METHODS
   113 
   114 This section lists and describes all driver methods. All the driver methods will receive driver object ($self) as the first argument. Methods that pertain to an individual session (such as C<retrieve()>, C<store()> and C<remove()>) will also receive session id ($sid) as the second argument.
   115 
   116 Following list describes every driver method, including its argument list and what step of session's life they will be invoked. Understanding this may help driver authors.
   117 
   118 =over 4
   119 
   120 =item retrieve($self, $sid)
   121 
   122 Called whenever a specific session is requested either via C<< CGI::Session->new() >> or C<< CGI::Session->load() >> syntax. Method should try to retrieve data associated with C< $sid > and return it. In case no data could be retrieved for C< $sid > 0 (zero) or "" should be returned. undef must be returned only to signal error. Error message should be set via set_error(), which can be inherited from L<CGI::Session::ErrorHandler|CGI::Session::ErrorHandler>. 
   123 
   124 Tip: set_error() always returns undef. Use it for your advantage.
   125 
   126 =item store($self, $sid, $datastr)
   127 
   128 Called whenever modified session data is to be stored back to disk. This happens whenever CGI::Session->flush() is called on modified session. Since CGI::Session->DESTROY() calls flush(), store() gets requested each time session object is to be terminated.
   129 
   130 C< store() > is called both to store new sessions and to update already stored sessions. It's driver author's job to figure out which operation needs to be performed.
   131 
   132 $datastr, which is passed as the third argument to represents B<already serialized> session data that needs to be saved.
   133 
   134 store() can return any true value indicating success or undef on failure. Error message should be passed to set_error()
   135 
   136 =item remove($self, $sid)
   137 
   138 Called whenever session data is to be deleted, which is when CGI::Session->delete() is called. Should return any true value indicating success, undef on failure. Error message should be logged in set_error().
   139 
   140 =item traverse($self, \&coderef)
   141 
   142 Called only from within CGI::Session->find(). Job of traverse() is to call \&coderef for every single session stored in disk passing session's id as the first and only argument: C<< $coderef->( $sid ) >>
   143 
   144 =item init($self)
   145 
   146 Optional. Called whenever driver object is to be initialized, which happens only once during the lifecycle of CGI::Session object. Here you can do driver-wide initialization, such as to open connection to a database server.
   147 
   148 =item DESTROY($self)
   149 
   150 Optional. Perl automatically calls this method on objects just before they are to be terminated. This gives your driver chance to close any database connections or close any open file handles.
   151 
   152 =back
   153 
   154 =head2 NOTES
   155 
   156 =over 4
   157 
   158 =item *
   159 
   160 All driver F<.pm> files must be lowercase!
   161 
   162 =item *
   163 
   164 DBI-related drivers are better off using L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI> as base, but don't have to.
   165 
   166 =back
   167 
   168 =head1 LICENSING
   169 
   170 For support and licensing see L<CGI::Session|CGI::Session>.
   171 
   172 @