GPMSWiki/DeveloperDocumentation/MigrationHelp/SessionManagementChanges

Changes in the Session Management

The new Sessionmanagement module is completely new and build from scratch. It supports hierarchical sessions, and also anonymous sessions. Complete redesign implies vast changes throughout the API. Most functions do no longer exist or have changes. So this thing is still a real pain in the ass.

Classes

You can have multiple sessions of different classes. An application specific subclass of Session::GPMS is mandatory. It has to be placed in the application subdirectory share/perl/Session/GPMS.

Here is a simple example:

package Session::GPMS::EMMAII;

=head1 NAME

Session::GPMS::EMMA2

=head1 DESCRIPTION

Sample implementation of a Session::GPMS::Application class, using GPMS::Application_Frame::Sample

=cut

use strict;
use warnings;
use GPMS::Application_Frame::EMMAII;

use base qw(Session::GPMS::Application);


1;

### Begin Class Methods ###

sub AppFrameClass {
    # we use GPMS::Application_Frame::EMMAII
    return "GPMS::Application_Frame::EMMAII";
}

sub NeedSingleton {
    # we cannot have multiple instances of an EMMA apllications at the moment
    # this could change in the future....
    return 1;
}

### End Class Methods ###

__END__

Initialization of Sessions

With the new session management there are normally al least two session:

• Session::Master -- the root session from which others can be derived
• Session::GPMS::<YourApp> -- an application-specific session, sublclass of Session::GPMS as given above

The session management supports multiple sessions of the same type, if your application does not: use singleton session. currently most of our apps only support a single instance.

To retrieve valid sessions for your application the following steps have to be performed:

1. No Session at all -> check if browser accepts cookies
2. Check if you can resume Session::Master, if not: new Session::Master. The master session already sets the cookie.
3. Check if you are having an authenticated session, that is have already given login/passw
4. If not: get credentials and
5. authenticate, getting a Session::GPMS::<YourApp>
6. Set the project for this session

once you have and authenticated Session::GPMS::<YourApp> the session can be resumed using Session::GPMS::<[[YourApp]]>->loadSingleton($masterSession); if it is a singleton session.

Here is a lengthy stub for a login script (taken from GenDB login script). The code fragment is encapsulated in a function, so return is used several times to exit the function.

    # resume master session and print HTTP header
    my $master_session;
    eval {
        $master_session = Session::Master->new();
        print $master_session->header();
    };
    if (ref ($@) && $@->isa("Session::NoActiveSessionException")) {
        # we do not have an active session
        # check whether this is the cookie-test invocation
        if ($q->param('cookie_test')) {

            # show error about not accepting cookies ....
            
            return;
        }
        else {
            # first invocation, let's check whether the user accepts cookies
            $master_session = Session::Master->new(1);
            my $url = $q->self_url()."?cookie_test=1";
            print $master_session->header();
            print $q->start_html(-head=>$q->meta({-http_equiv=>'refresh',
                                                  -content => "2;$url"}));

            print "Checking for cookies, you will be redirected to ".$q->a({-href=>$url},"this page.");
            print $q->end_html();
            return;
        }
    }
    elsif (ref($@)) {
        # some other error, show some error message to the user
        return;
    }

    unless ($master_session->isAuthenticated()) {
        unless ($q->param('login')) {

            # show the login form

            return;
        }
        else {
            # try to authenticate the user and show the
            # project selection list
            eval {
                # this only creates a GPMS sub session, not a GenDB sub session
                # otherwise you would end up with a dangling GenDB sub session if the
                # user closes the window after authetication
                $master_session->addGPMSSubSession($q->param('login'), $q->param('pass'));
            };
            if ($@) {

                # failed to authenticate, show an error message to the use
                
                return;
            }
        }
    }

    # try to load an exiting GenDB session. This will return undef if no
    # GenDB sub session exists yet
    my $session = Session::GENDB->loadSingleton($master_session);

    if ($q->param('project')) {
        if (ref($session)) {
            # ensure that the session is for the same project
            # otherwise this is an error
            if ($session->param('project_name')) {
                if ($session->param('project_name') ne $q->param('project')) {
                    print error_page($q->p("Requested to use project ".
                                           $q->b($q->param('project')).
                                           ", but there's already an active session for project ".
                                           $q->b($session->param('project')).".").
                                     $q->br().
                                     "Click ".$q->a({-href => $session->resumeURL()}," here ")." to resume the active session.".$q->br()."To change the project either switch to the project in the GenDB main window or log out and log in again.");
                    return;
                }
            }
        }
        else {
            # no session yet, initialize a new one
            $session = Session::GENDB->create($master_session);
        }
        
        # set the requested project
        my $project = $master_session->getGPMSSubSession()->
            getApplicationFrame()->
            gpms_master()->
            Project->init_name($q->param('project'));
        $session->setProject($project);
    }

    if (ref($session) && $session->param('project_name')) {
        my $tmpl = HTML::Template->new(filename=>get_template_file('index.tmpl'));
        $tmpl->param(CGI_LINK  => CGI_LINK,
                     CSS_FILE  => CSS_FILE,
                     TITLE => page_title('Main Window'));
        
        # if the user has not used this project before, 
        # create a default user configuration
        my $config = $session->getConfig();
        
        # we use a default value that is unlikely to be changed or removed
        my $test_value = $config->get_config_entity('ObservationWidget',
                                                    'cache');
        if (!defined $test_value || !$test_value) {
            $config->clear();
            $config->clear();
            GENDB::Web::DefaultPreferences::set_default_preferences($session->getMaster(), $config);
        }
        
        my $framespace = $config->get_config_entity('RegionCanvas',
                                                    'FrameSpace') ? 
                                                        $config->get_config_entity('RegionCanvas', 'FrameSpace') : 35;
        
        my $width = $q->param('width') || SIZEX_DEFAULT;
        my $height = $q->param('height') || SIZEY_DEFAULT;
        $tmpl->param(MAIN_SIZEX => $width,
                     MAIN_FRAMEY => $framespace * 8 + 240);
        
        # set additional params like region, contig and action for navigation 
        # with the speed of light
        
        if ($q->param('region')) {
            $session->param('region', $q->param('region'));
        }
        if ($q->param('contig')) {
            $session->param('contig', $q->param('contig'));
            }
        if ($q->param('action')) {
            $session->param('action', $q->param('action'));
        }
            
        print $tmpl->output();
    } 
    else { 
        ## no project selected yet, display project selection
        my $projects = get_project_list($master_session->getGPMSSubSession());
        unless (scalar @$projects) {
            print error_page($q, 'Error while logging into GenDB','No GenDB projects found for the user');
        }
        else {
            my $tmpl = HTML::Template->new(filename=>get_template_file('prj_select.tmpl'));
            $tmpl->param(CGI_LINK =>CGI_LINK,
                         CSS_FILE => CSS_FILE,
                         USER => $master_session->getGPMSSubSession()->
                         getApplicationFrame()->user->name(),
                         project_loop => $projects,
                         TITLE => page_title('Project selection'));
            print $tmpl->output;
        } # end of no project param set
    } 

API

The API has been rewritten to be consistent and easy to use.

Session parameter

Session parameters are handled by a number of functions:

• param(name, [value]) gets or sets a session parameter
• hasParam(name) returns true if a session parameter with the given name exists
• deleteParam(name) removed the session parameter
• getParams() returns a list of all session parameter names

Certain functions of the old API are not supported anymore; they can be easily substituted by short chunks of code. Permanent session parameters are also not implemented in the new session management due to its limited use and added maintance overhead.

Other discontinued methods

These methods were specific for GPMS based sessions in the former session management; they counterparts (if existing) are implemented for Session::GPMS::Application sub classes only.

• query use CGI->new() to get a CGI object. The CGI module stores an internal copy of an initialized object during page processing, so calling new several times has only very little to no overhead
• master used to return the /!\ application frame /!\ in the previous session management and was removed for the obvious reason. If you are using a sub class of Session::GPMS::Application, use getApplicationFrame() to get the application frame of the session and use the application_master() and gpms_master() methods to get the master objects.
• login_name,password etc. Also use the application frame to get these values. Keep in mind that the new sessionmanagement uses role accounts. You have to use the real_login() method of the application frame to get the name of the user. Passwords are only stored as hashes. Clear text passwords ARE NOT AVAILABLE ANYMORE.