# Driver.pm,v 3.5 2005/02/09 08:30:38 sherzodr Exp
use strict;
#use diagnostics;
use Carp;
$CGI::Session::Driver::VERSION = "4.00";
@CGI::Session::Driver::ISA = qw(CGI::Session::ErrorHandler);
sub new {
my $class = shift;
my ($args) = @_;
if ( $args ) {
unless ( ref $args ) {
croak "Invalid argument type passed to driver: " . Dumper($args);
}
} else {
$args = {};
}
my $self = bless ($args, $class);
return $self->init ? $self : undef;
}
sub init {}
sub retrieve {
croak "retrieve(): " . ref($_[0]) . " failed to implement this method!";
}
sub store {
croak "store(): " . ref($_[0]) . " failed to implement this method!";
}
sub remove {
croak "remove(): " . ref($_[0]) . " failed to implement this method!";
}
sub dump {
require Data::Dumper;
my $d = Data::Dumper->new([$_[0]], [ref $_[0]]);
return $d->Dump;
}
1;
__END__;
=pod
=head1 NAME
CGI::Session::Driver - CGI::Session driver specifications
=head1 WARNING
Version 2.01 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.
If you need any help converting your driver to meet current specs, send me an e-mail. For support information see
L<CGI::Session|CGI::Session>
=head1 SYNOPSIS
require CGI::Session::Driver;
@ISA = qw( CGI::Session::Driver );
=head1 DESCRIPTION
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.
=head1 WHAT IS A DRIVER
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()">, L<store()|/"store()"> and L<remove()|/"remove()"> methods.
=head2 BLUEPRINT
The best way of learning the specs is to look at a blueprint of a driver:
package CGI::Session::Driver::your_driver_name;
use strict;
use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
sub init {
my ($self) = @_;
# optional
}
sub DESTROY {
my ($self) = @_;
# optional
}
sub store {
my ($self, $sid, $datastr) = @_;
# Store $datastr, which is an already serialized string of data.
# Return any true value on success, undef failure.
# Set error message using $self->set_error()
}
sub retrieve {
my ($self, $sid) = @_;
# Return $datastr, which was previously stored using above store() method.
# Return $datastr if $sid was found. Return 0 or "" if $sid doesn't exist
# in the datastore. Return undef to indicate failure. Set error message
# using $self->set_error()
}
sub remove {
my ($self, $sid) = @_;
# Remove storage associated for $sid. Return any true value indicating success,
# or undef on failure. Set error message using $self->set_error()
}
All the attributes passed as the second argument to CGI::Session's new() or load() methods will automatically
be made driver's object attributes. For example, if session object was initialized as following:
$s = CGI::Session->new("driver:your_driver_name", undef, {Directory=>'/tmp/sessions'});
You can access value of 'Directory' from within your driver like so:
sub store {
my ($self, $sid, $datastr) = @_;
my $dir = $self->{Directory}; # <-- in this example will be '/tmp/sessions'
}
Optionally, you can define C<init()> method within your driver to do driver specific global initialization. C<init()> method
will be envoked only once during the lifecycle of your driver, which is the same as the lifecycle of a session object.
For examples of C<init()> look into the source code of native CGI::Session drivers.
=head2 NOTES
=over 4
=item *
All driver F<.pm> files must be lowercase!
=item *
DBI-related drivers are better off using L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI> as base, but don't have to.
=back
=head1 LICENSING
For support and licensing see L<CGI::Session|CGI::Session>.
=cut