.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Plugin::Session::Store::Delegate 3pm"
.TH Catalyst::Plugin::Session::Store::Delegate 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Plugin::Session::Store::Delegate \- Delegate session storage to an
application model object.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Catalyst::Plugin::Session::Store::Delegate;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This store plugins makes delegating session storage to a first class object
model easy.
.SH "THE MODEL"
.IX Header "THE MODEL"
The model is used to retrieve the delegate object for a given session \s-1ID.\s0
.PP
This is normally something like \s-1DBIC\s0's resultset object.
.PP
The model must respond to the \f(CW\*(C`get_delegate\*(C'\fR method or closure in the sesion
config hash (defaults to \f(CW\*(C`get_session_store_delegate\*(C'\fR).
.PP
An object \fBmust always\fR be returned from this method, even if it means
autovivifying. The object may optimize and create itself lazily in the actual
store only when \->store methods are actually called.
.SH "THE DELEGATE"
.IX Header "THE DELEGATE"
A single delegate belongs to a single session \s-1ID.\s0 It provides storage space for
arbitrary fields.
.PP
The delegate object must respond to method calls as per the
\&\f(CW\*(C`session_store_delegate_key_to_accessor\*(C'\fR method's return values.
.PP
Typically this means responding to \f(CW$obj\fR\->$field type accessors.
.PP
If necessary, the delegate should maintain an internal reference count of the
stored fields, so that it can garbage collect itself when all fields have been
deleted.
.PP
The fields are arbitrary, and are goverend by the various session plugins.
.PP
The basic keys that must be supported are:
.IP "expires" 4
.IX Item "expires"
A timestamp indicating when the session will expire.
.Sp
If a store so chooses it may clean up session data after this timestamp, even
without being told to delete.
.IP "session" 4
.IX Item "session"
The main session data hash.
.Sp
Might not be used, if only \f(CW\*(C`flash\*(C'\fR exists.
.IP "flash" 4
.IX Item "flash"
A hash much like the main session data hash, which can be created and deleted
multiple times per session, as required.
.PP
The delegate must also respond to the \f(CW\*(C`flush\*(C'\fR method which is used to tell the
store delegate that no more set/get/delete methods will be invoked on it.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "session_store_delegate_key_to_accessor $key, $operation" 4
.el .IP "session_store_delegate_key_to_accessor \f(CW$key\fR, \f(CW$operation\fR" 4
.IX Item "session_store_delegate_key_to_accessor $key, $operation"
This method implements the various calling conventions. It accepts a key and an
operation name (\f(CW\*(C`get\*(C'\fR, \f(CW\*(C`set\*(C'\fR or \f(CW\*(C`delete\*(C'\fR), and must return a method (could
be a string or a code reference), and an optional list of arguments that will
be invoked on the delegate.
.Sp
The default version splits \f(CW$key\fR on the first colon, extracting the field name
and the \s-1ID.\s0 It then returns the unaltered field name, and if the operation is
\&'delete' also provides the extra argument \f(CW\*(C`undef\*(C'\fR. This works with accessor
semantics like these:
.Sp
.Vb 3
\&    $obj\->foo;
\&    $obj\->foo("bar");
\&    $obj\->foo(undef);
.Ve
.Sp
To facilitate a convention like
.Sp
.Vb 3
\&    $obj\->get_foo;
\&    $obj\->set_foo("bar");
\&    $obj\->delete_foo;
.Ve
.Sp
or
.Sp
.Vb 3
\&    $obj\->get("foo");
\&    $obj\->set("foo", "bar");
\&    $obj\->delete("foo");
.Ve
.Sp
simply override this method. You may look in the source of this module to find
commented out versions which should help you.
.IP "session_store_delegate" 4
.IX Item "session_store_delegate"
This method returns the delegate, which may be cached in \f(CW$c\fR.
.ie n .IP "get_session_store_delegate $id" 4
.el .IP "get_session_store_delegate \f(CW$id\fR" 4
.IX Item "get_session_store_delegate $id"
This method should get the delegate object for a given \s-1ID.\s0 See \*(L"\s-1THE MODEL\*(R"\s0
for more details.
.IP "session_store_model" 4
.IX Item "session_store_model"
This method should return the model that will provide the delegate object.The
default implementation will simply return
\&\f(CW\*(C`$c\->model( $c\->session_store_model_name )\*(C'\fR.
.IP "session_store_model_name" 4
.IX Item "session_store_model_name"
Returns \f(CW\*(C`$c\->config\->{session}{model_name} || "Sessions"\*(C'\fR.
.ie n .IP "finalize_session_delegate $delegate" 4
.el .IP "finalize_session_delegate \f(CW$delegate\fR" 4
.IX Item "finalize_session_delegate $delegate"
Invokes the \f(CW\*(C`flush\*(C'\fR method on the delegate. May be overridden if that behavior
is inappropriate.
.ie n .IP "get_session_data $key" 4
.el .IP "get_session_data \f(CW$key\fR" 4
.IX Item "get_session_data $key"
.PD 0
.ie n .IP "store_session_data $key, $value" 4
.el .IP "store_session_data \f(CW$key\fR, \f(CW$value\fR" 4
.IX Item "store_session_data $key, $value"
.ie n .IP "delete_session_data $key" 4
.el .IP "delete_session_data \f(CW$key\fR" 4
.IX Item "delete_session_data $key"
.PD
These methods translate the store \s-1API\s0 into the delegate \s-1API\s0 using
\&\f(CW\*(C`session_store_delegate_key_to_accessor\*(C'\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
Yuval Kogman, \f(CW\*(C`nothingmuch@woobling.org\*(C'\fR
.PP
Tomas Doran, (t0m) \f(CW\*(C`bobtfish@bobtfish.net\*(C'\fR (current maintainer)
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 2006 the aforementioned authors. 
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.