/ 
OpenInteract-1.99_01
River stage zero No dependents
/ OpenInteract2::Session

NAME

OpenInteract2::Session - Implement session handling in the framework

SYNOPSIS

# Creating a session is done in OpenInteract2::Request

use OpenInteract2::Constants qw( SESSION_COOKIE );
...

my $session_id = $self->cookie( SESSION_COOKIE );
my $session_class = CTX->server_config->{session_info}{class};
my $session = $session_class->create( $session_id );
$request->session( $session );

# Access the data the session from any handler

my $session = CTX->request->session;
$session->{my_stateful_data} = "oogle boogle";
$session->{favorite_colors}{red} += 5;

# And from any template you can use the OI template plugin (see
# OpenInteract2::ContentGenerator::TT2Plugin)

<p>The weight of your favorite colors are:
[% FOREACH color = keys OI.session.favorite_colors %]
  * [% color %] -- [% OI.session.favorite_colors.color %]
[% END %]

# Saving a session is done in OpenInteract2::Response

OpenInteract2::Session->save( CTX->request->session );

DESCRIPTION

Sessions are a fundamental part of OpenInteract, and therefore session handling is fairly transparent. We rely on Apache::Session to do the heavy-lifting for us.

This handler has two public methods: create() and save(). Guess in which order they are meant to be called?

This class also requires you to implement a subclass that overrides the _create_session method with one that returns a valid Apache::Session tied hashref. OpenInteract provides OpenInteract2::Session::DBI for DBI databases, OpenInteract2::Session::SQLite for SQLite databases, and , OpenInteract2::Session::File using the filesystem. Implementations using other media are left as an exercise for the reader. (More below.)

You can create sessions that will expire if not used in a specified amount of time by setting the session_info.expires_in server configuration key. See the description below in CONFIGURATION for more information.

METHODS

create( [ $session_id ] )

Get the session_id and fetch a session for this ID. If an ID is unsupplied the implementation should create an empty but still active session for us.

If no session ID is supplied we set the 'is_new' key in the session supplied by the implemntation so that save() knows to send a cookie.

Returns: tied hashref if session implementation ran correctly, normal hashref if not.

save()

Persist (create or update) the session for later. If the 'is_new' key was set in the session by the create() method we also use OpenInteract2::Cookie to create a new cookie and put it in the response. The expiration for the generated cookie is pulled from the session itself (using the key 'expiration') or the value set in the server configuration key 'session_info.expiration'.

If either is set the method will remove the 'is_new' and 'expiration' keys from the session.

This method will not serialize the session if it is empty.

CONFIGURATION

The following configuration keys are used:

  • session_info.class (REQUIRED)

    Specifies the OpenInteract2 session implementation to use. This class is required at startup in OpenInteract2::Setup#require_session_classes.

  • session_info.impl_class (optional)

    Specifies the Apache::Session session implementation to use. While not strictly optional every OpenInteract2 session implementation does demand it. This class is required at startup in OpenInteract2::Setup#require_session_classes.

  • session_info.expiration (optional)

    Used by save() when creating a new session to set the time a session cookie lasts on the user's browser. See CGI for an explanation of the relative date strings accepted.

  • session_info.expires_in (optional)

    Used to set the time (in number of minutes) greater than which a session will expire due to inactivity. This is a server-side setting and is exclusive of the expiration setting above.

SUBCLASSING

Creating your own session implementation is fairly easy. You must:

Validating Your Configuration

Before a session is created you have the opportunity to check your configuration and ensure all parameters are set as required. The only argument you get is the server configuration settings under 'session_info'.

To indicate errors return a list of messages and they'll be passed along to the proper authorities. Here's an example:

sub _validate_config {
    my ( $class, $session_config ) = @_;
    my @errors = ();
    unless ( $session_config->{params}{doodad} ) {
        push @errors, "Session parameter 'doodad' must be set";
    }
    unless ( $session_config->{impl_class} ) {
        push @errors, "You must define a session implementation in " .
                      "server configuration key 'session_info.impl_class'";
    }
    return @errors;
}

If errors are returned from _validate_config the session is never materialized, _create_session is never called.

Creating a Session

Like _validate_config the _create_session method is given the session information from the server configuration. It's also given a session ID for which the implementation should retrieve the data. If you've written a validation routine you can assume the session configuration is ok.

The _create_session method should either throw an exception or return a tied hashref, nothing else. If no session ID is passed in the method should create a tied hashref without any data besides the generated session ID.

Here's a generic example:

sub _create_session {
    my ( $class, $session_config, $session_id ) = @_;
    my $impl_class = $session_config->{impl_class};
    my $session_params = $session_config->{params};
    my %session = ();
    tie %session, $impl_class, $session_id, $session_params;
    return \%session;
}

It's fine the tie call dies -- the caller will catch the error and be able to move on properly.

BUGS

None known.

SEE ALSO

Apache::Session

OpenInteract2::Constants where the SESSION_COOKIE is defined.

OpenInteract2::ContentGenerator::TT2Plugin: makes the session hash information available to the template

OpenInteract2::Cookie -- routines for parsing, creating, setting cookie information so we can match up users with session information

COPYRIGHT

Copyright (c) 2001-2003 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>