OpenInteract2 Documentation: OpenInteract2::SessionManager

NAME

OpenInteract2::SessionManager - Implement session management for OpenInteract

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->lookup_session_config->{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::TT2::Plugin)
 
 <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::SessionManager->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::SessionManager::DBI for DBI databases, OpenInteract2::SessionManager::SQLite for SQLite databases, and , OpenInteract2::SessionManager::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:

Subclass OpenInteract2::SessionManager
Implement _validate_config()
Implement _create_session()

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.

COPYRIGHT

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>

Generated from the OpenInteract 1.99_06 source.