NAME¶
Apache::SessionX - An extented persistence framework for session data
SYNOPSIS¶
DESCRIPTION¶
Apache::SessionX extents Apache::Session. It was initially written to use
Apache::Session from inside of HTML::Embperl, but is seems to be useful
outside of Embperl as well, so here is it as standalone module.
Apache::Session is a persistence framework which is particularly useful for
tracking session data between httpd requests. Apache::Session is designed to
work with Apache and mod_perl, but it should work under CGI and other web
servers, and it also works outside of a web server altogether.
Apache::Session consists of five components: the interface, the object store,
the lock manager, the ID generator, and the serializer. The interface is
defined in SessionX.pm, which is meant to be easily subclassed. The object
store can be the filesystem, a Berkeley DB, a MySQL DB, an Oracle DB, or a
Postgres DB. Locking is done by lock files, semaphores, or the locking
capabilities of MySQL and Postgres. Serialization is done via Storable, and
optionally ASCII-fied via MIME or
pack(). ID numbers are generated via
MD5. The reader is encouraged to extend these capabilities to meet his own
requirements.
INTERFACE¶
The interface to Apache::SessionX is very simple: tie a hash to the desired
class and use the hash as normal. The constructor takes two optional
arguments. The first argument is the desired session ID number, or undef for a
new session. The second argument is a hash of options that will be passed to
the object store and locker classes.
Addtional Attributes for TIE¶
- lazy
- By specifying this attribute, you tell Apache::Session to not do any
access to the object store, until the first read or write access to the
tied hash. Otherwise the tie function will make sure the hash exist
or creates a new one.
- create_unknown
- Setting this to one causes Apache::Session to create a new session with
the given id (or a new id, depending on "recreate_id") when the
specified session id does not exists. Otherwise it will die.
- recreate_id
- Setting this to one causes Apache::Session to create a new session id when
the specified session id does not exists.
- idfrom
- instead of passing in a session id, you can pass in a string, from which
Apache::SessionX generates the id in case it needs one. The main advantage
from generating the id by yourself is, that in 'lazy' mode the id is only
generated when the session is accessed.
- newid
- Setting this to one will cause Apache::SessionX to generate a new id every
time the session is saved. If you call "getid" or
"getids" it will return the new id that will be used to save the
data.
- config
- Use predefiend config from Apache::SessionX::Config, which is configured
at package installation time. On Debian, these may be altered by running
"dpkg-reconfigure libapache-sessionx-perl".
- object_store
- Specify the class for the object store. (The Apache::Session:: prefix is
optional) Only for Apache::Session 1.00.
- lock_manager
- Specify the class for the lock manager. (The Apache::Session:: prefix is
optional) Only for Apache::Session 1.00.
- Store
- Specify the class for the object store. (The Apache::Session::Store prefix
is optional) Only for Apache::Session 1.5x.
- Lock
- Specify the class for the lock manager. (The Apache::Session::Lock prefix
is optional) Only for Apache::Session 1.5x.
- Generate
- Specify the class for the id generator. (The Apache::Session::Generate
prefix is optional) Only for Apache::Session 1.5x.
- Serialize
- Specify the class for the data serializer. (The Apache::Session::Serialize
prefix is optional) Only for Apache::Session 1.5x.
Example using attrubtes to specfiy store and object classes instead of a derived
class:
use Apache::SessionX
tie %session, 'Apache::SessionX', undef,
{
object_store => 'DBIStore',
lock_manager => 'SysVSemaphoreLocker',
DataSource => 'dbi:Oracle:db'
};
NOTE: Apache::SessionX will "require" the nessecary additional perl
modules for you.
Addtional Methods¶
- setid ($id)
- Set the session id for futher accesses.
- setidfrom ($string)
- Set the string that is passed to the generate function to compute the
id.
- getid
- Get the session id. The difference to using $session{_session_id} is, that
in lazy mode, getid will not create a new session id, if it doesn't
exists.
- getids ($init)
- return the an array where the first element is the initial id, the second
element is the current id and the third element is set to true, when the
session data was modified. If the session was deleted, the initial id
(first array value) will be set to '!DELETE'.
If the optional parameter $init is set to true, getids will initialize the
session (i.e. read from the store) when not already done.
- cleanup
- Writes any pending data, releases all locks and deletes all data from
memory.
SEE ALSO¶
- See documentation of Apache::Session for more information about it's
internals
- Apache::SessionX::Generate::MD5
- Apache::Session::Store::*
- Apache::Session::Lock::*
- Apache::Session::Serialize::*
AUTHORS¶
Gerald Richter <richter@dev.ecos.de> is the current maintainer.
This class was written by Jeffrey Baker (jeffrey@kathyandjeffrey.net) but it is
taken wholesale from a patch that Gerald Richter (richter@ecos.de) sent me
against Apache::Session.