CGI::Session::Driver man page on Oracle

Man page or keyword search:  
man Server   33470 pages
apropos Keyword Search (all sections)
Output format
Oracle logo
[printable version]

CGI::Session::Driver(3User Contributed Perl DocumentatiCGI::Session::Driver(3)

NAME
       CGI::Session::Driver - CGI::Session driver specifications

WARNING
       Version 4.0 of CGI::Session's driver specification is 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 CGI::Session

SYNOPSIS
	   require CGI::Session::Driver;
	   @ISA = qw( CGI::Session::Driver );

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.

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 .pm file that inherits from CGI::Session::Driver and
       defines retrieve(), store() and remove() methods.

   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.
	   }

	   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
	       }

	   sub remove {
	       my ($self, $sid) = @_;
	       # Remove storage associated with $sid. Return any true value indicating success,
	       # or undef on failure.
	   }

	   sub traverse {
	       my ($self, $coderef) = @_;
	       # execute $coderef for each session id passing session id as the first and the only
	       # argument
	   }

	   1;

       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 "init()" method within your driver to do
       driver specific global initialization. "init()" method will be invoked
       only once during the lifecycle of your driver, which is the same as the
       lifecycle of a session object.

       For examples of "init()" look into the source code of native
       CGI::Session drivers.

METHODS
       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 "retrieve()",
       "store()" and "remove()") will also receive session id ($sid) as the
       second argument.

       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.

       retrieve($self, $sid)
	   Called whenever a specific session is requested either via
	   "CGI::Session->new()" or "CGI::Session->load()" syntax. Method
	   should try to retrieve data associated with	$sid  and return it.
	   In case no data could be retrieved for  $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
	   CGI::Session::ErrorHandler.

	   Tip: set_error() always returns undef. Use it for your advantage.

       store($self, $sid, $datastr)
	   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.

	   " 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.

	   $datastr, which is passed as the third argument to represents
	   already serialized session data that needs to be saved.

	   store() can return any true value indicating success or undef on
	   failure. Error message should be passed to set_error()

       remove($self, $sid)
	   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().

       traverse($self, \&coderef)
	   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: "$coderef->( $sid )"

       init($self)
	   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.

       DESTROY($self)
	   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.

   NOTES
       ·   All driver .pm files must be lowercase!

       ·   DBI-related drivers are better off using CGI::Session::Driver::DBI
	   as base, but don't have to.

LICENSING
       For support and licensing see CGI::Session.

perl v5.16.3			  2008-07-15	       CGI::Session::Driver(3)
[top]

List of man pages available for Oracle

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net