local-lib5/man/man3/Catalyst::Plugin::Session::Store.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Catalyst::Plugin::Session::Store 3"
 127 .TH Catalyst::Plugin::Session::Store 3 "2009-10-06" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Catalyst::Plugin::Session::Store \- Base class for session storage
 134 drivers.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    package Catalyst::Plugin::Session::Store::MyBackend;
 139 \&    use base qw/Catalyst::Plugin::Session::Store/;
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 This class doesn't actually provide any functionality, but when the
 144 \&\f(CW\*(C`Catalyst::Plugin::Session\*(C'\fR module sets up it will check to see that
 145 \&\f(CW\*(C`YourApp\->isa("Catalyst::Plugin::Session::Store")\*(C'\fR. When you write
 146 a session storage plugin you should subclass this module for this
 147 reason. This documentation is intended for authors of session storage
 148 plugins, not for end users.
 149 .SH "WRITING STORE PLUGINS"
 150 .IX Header "WRITING STORE PLUGINS"
 151 All session storage plugins need to adhere to the following interface
 152 specification to work correctly:
 153 .SS "Required Methods"
 154 .IX Subsection "Required Methods"
 155 .ie n .IP "get_session_data $key" 4
 156 .el .IP "get_session_data \f(CW$key\fR" 4
 157 .IX Item "get_session_data $key"
 158 .PD 0
 159 .ie n .IP "store_session_data $key, $data" 4
 160 .el .IP "store_session_data \f(CW$key\fR, \f(CW$data\fR" 4
 161 .IX Item "store_session_data $key, $data"
 162 .PD
 163 Retrieve or store session data by key.
 164 .Sp
 165 \&\f(CW$data\fR is currently either a hash reference (for most keys) or an
 166 integer value (for expires), but all value types should be supported.
 167 .Sp
 168 Keys are in the format \f(CW\*(C`prefix:id\*(C'\fR, where \f(CW\*(C`prefix\*(C'\fR is \f(CW\*(C`session\*(C'\fR,
 169 \&\f(CW\*(C`expires\*(C'\fR, or \f(CW\*(C`flash\*(C'\fR, and \f(CW\*(C`id\*(C'\fR is always the session \s-1ID\s0. Plugins
 170 such as Catalyst::Plugin::Session::PerUser store extensions to this
 171 format, such as \f(CW\*(C`user:username\*(C'\fR.
 172 .Sp
 173 It is suggested that the store should split on the colon and store the
 174 data more efficiently \- the \s-1API\s0 should remain stable, with the possible
 175 addition of new prefixes in the future.
 176 .Sp
 177 For example, \f(CW\*(C`Store::DBI\*(C'\fR maps \f(CW\*(C`expires:id\*(C'\fR a column of \f(CW\*(C`session:id\*(C'\fR
 178 by special-casing \f(CW\*(C`get_session_data\*(C'\fR and \f(CW\*(C`store_session_data\*(C'\fR for that
 179 key format, in order to ease the implementation of
 180 \&\f(CW\*(C`delete_expired_sessions\*(C'\fR.
 181 .Sp
 182 The only assurance stores are requred to make is that given
 183 .Sp
 184 .Vb 1
 185 \&    $c\->store_session_data( $x, $y );
 186 .Ve
 187 .Sp
 188 for any \f(CW$x\fR,
 189 .Sp
 190 .Vb 1
 191 \&    $y == $c\->get_session_data( $x )
 192 .Ve
 193 .Sp
 194 will hold.
 195 .ie n .IP "store_session_data ( $key, $data )" 4
 196 .el .IP "store_session_data ( \f(CW$key\fR, \f(CW$data\fR )" 4
 197 .IX Item "store_session_data ( $key, $data )"
 198 Store a session whose \s-1KEY\s0 is the first parameter and data is the second
 199 parameter in storage.
 200 .Sp
 201 The second parameter is a hash reference, which should normally be
 202 serialized (and later deserialized by \f(CW\*(C`get_session_data\*(C'\fR).
 203 .ie n .IP "delete_session_data ( $key )" 4
 204 .el .IP "delete_session_data ( \f(CW$key\fR )" 4
 205 .IX Item "delete_session_data ( $key )"
 206 Delete the session whose \s-1KEY\s0 is the parameter.
 207 .IP "delete_expired_sessions" 4
 208 .IX Item "delete_expired_sessions"
 209 This method is not called by any code at present, but may be called in the
 210 future, as part of a Catalyst-specific maintenance script.
 211 .Sp
 212 If you are wrapping around a backend which manages its own auto expiry
 213 you can just give this method an empty body.
 214 .SS "Error handling"
 215 .IX Subsection "Error handling"
 216 All errors should be thrown using Catalyst::Exception. Return values
 217 are not checked, and are assumed to be \s-1OK\s0. Missing values are not errors.
 218 .SS "Auto-Expiry on the Backend"
 219 .IX Subsection "Auto-Expiry on the Backend"
 220 Storage plugins are encouraged to use \f(CW\*(C`$c\->session_expires\*(C'\fR, \f(CW\*(C`$c\->config(\*(AqPlugin::Session\*(Aq => { expires => $val })\*(C'\fR, or the storage of the
 221 \&\f(CW\*(C`expires:$sessionid\*(C'\fR key to perform more efficient expiration, but only
 222 for the key prefixes \f(CW\*(C`session\*(C'\fR, \f(CW\*(C`flash\*(C'\fR and \f(CW\*(C`expires\*(C'\fR.
 223 .PP
 224 If the backend chooses not to do so, Catalyst::Plugin::Session will
 225 detect expired sessions as they are retrieved and delete them if
 226 necessary.
 227 .PP
 228 Note that session store that use this approach may leak disk space,
 229 since nothing will actively delete an expired session. The
 230 \&\f(CW\*(C`delete_expired_sessions\*(C'\fR method is there so that regularly scheduled
 231 maintenance scripts can give your backend the opportunity to clean up.