.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "WWWdb::Session 3"
.TH WWWdb::Session 3 "2003-04-15" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
WWWdb::Session \- Session\-Handling for WWWdb
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use WWWdb::Session;
.Ve
.PP
.Vb 3
\& $oSession   = Session->new($pDbHandle,
\&                            ["Id"        => $cSessionKey,]
\&                            ["IdLength"  => $iKeyLength]);
.Ve
.PP
.Vb 3
\& $cStateInfo = $oSession->getState($cStateName);
\& $cStateInfo = $oSession->setState($cStateName,
\&                                   $cStateValue);
.Ve
.PP
.Vb 1
\& $oSession->DESTROY();
.Ve
.PP
.Vb 3
\& $cId        = $oSession->getId();
\& $bIdInDb    = $oSession->getIdAlreadyInDb();
\& $iLength    = $oSession->getIdLength();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "The Session class"
.IX Header "The Session class"
Every WWWdb-Session is identyfied by a Session\-Id. This is a random
generated hex-string with 16 characters by default. Using this
session\-id, the user can continue sessions, he already has started.
.PP
For every session WWWdb can store state\-information, where the some
information for the user can be placed. Every time this session
gets re\-acitvated, the session-parameters for \fIthis\fR session
get used.
.PP
Internally the state-information is stored in the database in the
table \fBwwwdb_state\fR. When a Session-object gets allocated, the
corresponding data will be fetched from the database. When the
application runs, a cache of this parameters will be used.
The DESTROY-method will write the cache back to the database.
.Sh "Note"
.IX Subsection "Note"
.RS 4
If you want to flush all Objects to the Database during the session
you only have to re-create the session\-object. All changed objects
will be stored in the database and a new object with the actual values
gets allocated.
.Sp
Pleas note, that you will get trouble, when you set up two instances
of the same session\-object, because the state-info is cached in the
object!
.RE
.Sh "Class Methods"
.IX Subsection "Class Methods"
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 3
\& $oSession   = Session->new($pDbHandle,
\&                            ["Id"       => $cSessionKey,]
\&                            ["IdLength" => $iKeyLength]);
.Ve
.Sp
When you want to create a new session\-class, you have to call this
constructor. Because you want to acces the database we need the
DBI-database-handle \fIpDbHandle\fR. The \fIcSessionKey\fR is the
session\-key, for which the session should be created.  If you want a
new session\-key, you van give either \fI""\fR or \fIundef\fR as
parameter. The third thing we need, is the length of the key.
The default is 16. The minimum value is 4, the maximum is 32.
.Sp
When everything is ok, the session-data gets fetched, when the session
does already exist, or a new record whith the key \fIlast_acces\fR
will be inserted. Then the session-object will be returned.
.IP "\fBgetState\fR" 4
.IX Item "getState"
.Vb 1
\& $cStateInfo = $oSession->Session::getState($cStateName);
.Ve
.Sp
This method reads the value of the record with the id \fIcStateName\fR
from the internal hash and gives it back as the result. If the record
does not exist in the database, \fIundef\fR is returned.
.IP "\fBsetState\fR" 4
.IX Item "setState"
.Vb 2
\& $cStateInfo = $oSession->Session::setState($cStateName,
\&                                            $cStateValue);
.Ve
.Sp
setState sets the value of the state-record with the name
\&\fIcStateName\fR to \fIcStateValue\fR. If the value is \fIundef\fR the
corresponding record will be deleted from the database.
.IP "\fB\s-1DESTROY\s0\fR" 4
.IX Item "DESTROY"
This method will be called automatically b Perl, when the object is
going to be destroyed. Then the internal cache must be flushed to the
database. According to the existence of a record in the database
the following actions must be triggered:
.Sp
.Vb 12
\&  +----------+---------------------------+----------------------+
\&  | Already  |   What happened with the  |  What happens in the |
\&  | in db    |   Value of the Record     |  Database            |
\&  +----------+---------------------------+----------------------+
\&  | No       |   Set to some Value       |  INSERT record       |
\&  +----------+---------------------------+----------------------+
\&  | Yes      |   Set to some Value       |  UPDATE record       |
\&  +----------+---------------------------+----------------------+
\&  | No       |   Set to undef            |  - Ignore -          |
\&  +----------+---------------------------+----------------------+
\&  | Yes      |   Set to undef            |  DELETE record       |
\&  +----------+---------------------------+----------------------+
.Ve
.Sh "Class Attributes"
.IX Subsection "Class Attributes"
.IP "\fBId\fR" 4
.IX Item "Id"
.Vb 1
\& $cId        = $oSession->getId();
.Ve
.Sp
Get the Id of this session. (Read\-only)
.IP "\fBIdAlreadyInDb\fR" 4
.IX Item "IdAlreadyInDb"
.Vb 1
\& $bIdInDb    = $oSession->getIdAlreadyInDb();
.Ve
.Sp
True, when this session was already existing in the
database. (Read\-only)
.IP "\fBIdLength\fR" 4
.IX Item "IdLength"
.Vb 1
\& $iLength    = $oSession->getIdLength();
.Ve
.Sp
The length of the session\-id. (Read\-only)