NAME

       Catalyst::Plugin::Session::Store - Base class for session storage drivers.

SYNOPSIS

           package Catalyst::Plugin::Session::Store::MyBackend;
           use base qw/Catalyst::Plugin::Session::Store/;

DESCRIPTION

       This class doesn't actually provide any functionality, but when the
       "Catalyst::Plugin::Session" module sets up it will check to see that
       "YourApp->isa("Catalyst::Plugin::Session::Store")". When you write a session storage
       plugin you should subclass this module for this reason. This documentation is intended for
       authors of session storage plugins, not for end users.

WRITING STORE PLUGINS

       All session storage plugins need to adhere to the following interface specification to
       work correctly:

   Required Methods
       get_session_data $key
       store_session_data $key, $data
           Retrieve or store session data by key.

           $data is currently either a hash reference (for most keys) or an integer value (for
           expires), but all value types should be supported.

           Keys are in the format "prefix:id", where "prefix" is "session", "expires", or
           "flash", and "id" is always the session ID. Plugins such as
           Catalyst::Plugin::Session::PerUser store extensions to this format, such as
           "user:username".

           It is suggested that the store should split on the colon and store the data more
           efficiently - the API should remain stable, with the possible addition of new prefixes
           in the future.

           For example, "Store::DBI" maps "expires:id" a column of "session:id" by special-casing
           "get_session_data" and "store_session_data" for that key format, in order to ease the
           implementation of "delete_expired_sessions".

           The only assurance stores are required to make is that given

               $c->store_session_data( $x, $y );

           for any $x,

               $y == $c->get_session_data( $x )

           will hold.

       store_session_data ( $key, $data )
           Store a session whose KEY is the first parameter and data is the second parameter in
           storage.

           The second parameter is a hash reference, which should normally be serialized (and
           later deserialized by "get_session_data").

       delete_session_data ( $key )
           Delete the session whose KEY is the parameter.

       delete_expired_sessions
           This method is not called by any code at present, but may be called in the future, as
           part of a Catalyst-specific maintenance script.

           If you are wrapping around a backend which manages its own auto expiry you can just
           give this method an empty body.

   Error handling
       All errors should be thrown using Catalyst::Exception. Return values are not checked, and
       are assumed to be OK. Missing values are not errors.

   Auto-Expiry on the Backend
       Storage plugins are encouraged to use "$c->session_expires", "$c->config('Plugin::Session'
       => { expires => $val })", or the storage of the "expires:$sessionid" key to perform more
       efficient expiration, but only for the key prefixes "session", "flash" and "expires".

       If the backend chooses not to do so, Catalyst::Plugin::Session will detect expired
       sessions as they are retrieved and delete them if necessary.

       Note that session store that use this approach may leak disk space, since nothing will
       actively delete an expired session. The "delete_expired_sessions" method is there so that
       regularly scheduled maintenance scripts can give your backend the opportunity to clean up.

   Early Finalization
       By default the main session plugin will finalize during body finalization which ensures
       that all controller code related to the session has completed.  However some storage
       plugins may wish to finalize earlier, during header finalization.  For example a storage
       that saved state in a client cookie would wish this.  If a storage plugin wants to
       finalize early it should set $c->_needs_early_session_finalization to true.  Please note
       that if you do this in a storage plugin, you should warn users not to attempt to change or
       add session keys if you use a streaming or socket interface such as $c->res->write,
       $c->res->write_fh or $c->req->io_fh.