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