OpenInteract2::SessionManager - Implement session management for OpenInteract
# 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 );
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?
create()
save()
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.)
_create_session
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.
session_info.expires_in
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.
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.
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.
require
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.
expiration
Creating your own session implementation is fairly easy. You must:
Subclass OpenInteract2::SessionManager
Implement _validate_config()
_validate_config()
Implement _create_session()
_create_session()
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.
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.
tie
Apache::Session
OpenInteract2::Constants where the SESSION_COOKIE is defined.
SESSION_COOKIE
OpenInteract2::TT2::Plugin: makes the session data available to the template
OpenInteract2::Request is normally the process that creates a session from the cookie passed to us by the user or calling process.
Copyright (c) 2001-2005 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.
Chris Winters <chris@cwinters.com>
To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenInteract2::URL
CPAN shell
perl -MCPAN -e shell install OpenInteract2::URL
For more information on module installation, please visit the detailed CPAN module installation guide.