[catagits/Catalyst-Plugin-Session.git] / lib / Catalyst / Plugin / Session / Store.pm

#!/usr/bin/perl

package Catalyst::Plugin::Session::Store;

use strict;
use warnings;

__PACKAGE__;

__END__

=pod

=head1 NAME

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

=head1 SYNOPSIS

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

=head1 DESCRIPTION

This class doesn't actually provide any functionality, but when the
C<Catalyst::Plugin::Session> module sets up it will check to see that
C<< YourApp->isa("Catalyst::Plugin::Session::Store") >>.

When you write a session storage plugin you should subclass this module this
reason only.

=head1 WRITING STORE PLUGINS

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

=head2 Required Methods

=over 4

=item get_session_data $sid

Retrieve a session from storage, whose ID is the first parameter.

Should return a hash reference.

=item store_session_data $sid, $hashref

Store a session whose ID is the first parameter and data is the second
parameter in storage.

The second parameter is an hash reference, that should normally be serialized
(and later deserialized by C<get_session_data>).

=item delete_session_data $sid

Delete the session whose ID is the first parameter.

=item 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 it's own auto expiry you can
just give this method an empty body.

=back

=head2 Error handling

All errors should be thrown using L<Catalyst::Exception>. Return values are not
checked at all, and are assumed to be OK.

=head2 Auto-Expirey on the Backend

Storage plugins are encouraged to use C<< $c->config->{session}{expires} >> and
the C<__expires> key in the session data hash reference to auto expire data on
the backend side.

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

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

=cut
Commit	Line	Data
9e447f9d	1	#!/usr/bin/perl
	2
	3	package Catalyst::Plugin::Session::Store;
	4
	5	use strict;
	6	use warnings;
	7
9e447f9d	8	__PACKAGE__;
	9
	10	__END__
	11
	12	=pod
	13
	14	=head1 NAME
	15
	16	Catalyst::Plugin::Session::Store - Base class for session storage
	17	drivers.
	18
	19	=head1 SYNOPSIS
	20
45c0711b	21	package Catalyst::Plugin::Session::Store::MyBackend;
45c0711b	22	use base qw/Catalyst::Plugin::Session::Store/;
9e447f9d	23
	24	=head1 DESCRIPTION
	25
c80e9f04	26	This class doesn't actually provide any functionality, but when the
	27	C<Catalyst::Plugin::Session> module sets up it will check to see that
	28	C<< YourApp->isa("Catalyst::Plugin::Session::Store") >>.
	29
	30	When you write a session storage plugin you should subclass this module this
	31	reason only.
	32
	33	=head1 WRITING STORE PLUGINS
	34
	35	All session storage plugins need to adhere to the following interface
	36	specification to work correctly:
	37
	38	=head2 Required Methods
	39
	40	=over 4
	41
	42	=item get_session_data $sid
	43
	44	Retrieve a session from storage, whose ID is the first parameter.
	45
	46	Should return a hash reference.
	47
	48	=item store_session_data $sid, $hashref
	49
	50	Store a session whose ID is the first parameter and data is the second
	51	parameter in storage.
	52
	53	The second parameter is an hash reference, that should normally be serialized
	54	(and later deserialized by C<get_session_data>).
	55
	56	=item delete_session_data $sid
	57
	58	Delete the session whose ID is the first parameter.
	59
	60	=item delete_expired_sessions
	61
	62	This method is not called by any code at present, but may be called in the
	63	future, as part of a catalyst specific maintenance script.
	64
	65	If you are wrapping around a backend which manages it's own auto expiry you can
	66	just give this method an empty body.
	67
	68	=back
	69
	70	=head2 Error handling
	71
	72	All errors should be thrown using L<Catalyst::Exception>. Return values are not
	73	checked at all, and are assumed to be OK.
	74
	75	=head2 Auto-Expirey on the Backend
	76
	77	Storage plugins are encouraged to use C<< $c->config->{session}{expires} >> and
	78	the C<__expires> key in the session data hash reference to auto expire data on
	79	the backend side.
	80
	81	If the backend chooses not to do so, L<Catalyst::Plugin::Session> will detect
	82	expired sessions as they are retrieved and delete them if necessary.
	83
	84	Note that session storages that use this approach may leak disk space, since
	85	nothing will actively delete expired session. The C<delete_expired_sessions>
	86	method is there so that regularly scheduled maintenance scripts can give your
	87	backend the opportunity to clean up.
	88
9e447f9d	89	=cut
	90
	91