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:

sub login {  
    my $cgi = CGI->new();
    # get your parameters, or however they are named in your login page 
    # ICICIC: to your needs
    my $login = $cgi->param('login');
    my $pass = $cgi->param('pass');
    my $changeproject = $cgi->param('changeproject'); # did we receive a change request
    my $projectname =  $cgi->param('project');	  
   
    my $masterSession = undef; # this is the Master session
    my $myAppSession = undef; # this is the application specific session
    eval {
	# can we resume a session?
	$session = new Session::Master;
	print $session->header();
    };
    # errors are now raised by die-ing
    # if not:
    if (UNIVERSAL::isa($@, 'Session::NoActiveSessionException')) {
    # First time login, nothing is there
	### Check for cookies?
	if ($cgi->param('cookietest')) {
	    #### TODO: ERROR: Your browser doesnt accept cookies

	} else {
	    $session = new Session::Master (1); # initialize real-new session
	    print $session->header(); # got a cookie with that
	    my $url = $cgi->url().'?cookietest=1';
	    # ICICIC: other parameters must beadded here, probably
	    print $cgi->start_html(-head=>$cgi->meta({-http_equiv=>'refresh',
						      -content=>"2;$url"}));
	    # print checking for cookies for the user
	    print $cgi->p("Checking cookies, please wait...");
	    print $cgi->end_html();
	    return;
	}
    } elsif ($@) {
	### something else went wrong, error handling
       ## TODO: confess ...
    } 
    # if somebody wants to change the project, throw some 
    # data away:
    
    if ( $cgi->param('changeproject') ) {
	$session->deleteParam('project_name');
	$session->getApplicationFrame->release_project;

    }

### we got a Master session now, are we authenticated?  
    unless ($session->isAuthenticated) {

	### we must retrieve uname pw from cgiparam:
        # it's done at the top already
	
        # we must display the form first, if there is nothing!
	unless ($login && $pass) { # also prevents passwordless accounts!
	    ### TODO: show your login page
	    return;
	}
	
	### get an Application specific session:	
	eval {
	    $myAppSession = Session::GPMS::<YourAPP>-> # ICICIC:
		create_with_gpms($masterSession, $login, $pass);
	};
	if ($@) {
	 # something's wrong, $@ tells what
         # TODO: output error $@, most likely wrong credentials
	 return;
	} 
	
	### I'm authenticated now, show project selection page
        ### ICICIC: if your page does not support it
	my @projects =  @{$myAppSession
	    -> getApplicationFrame ->
	    get_available_projects_by_project_class()};
	# must also go here, if a project change is requested
	if (@projects) {
	    
	     my @prjnames = map {{name=>$_->name}} @projects;
	    @prjnames = sort { lc($a->{name}) cmp lc($b->{name}) } @prjnames;
	  ### TODO: show the list


	} else {
	    ### TODO: ERROR no projects found
	}


    } else {	
	unless ($projectname) {
	    ### I'm authenticated now, show project selection page
	    ### Got no project name, so show the project selection page
	    return;
	}

	# got project information from the CGI->param
	$myAppSession = Session::GPMS::<MyApp>->loadSingleton($masterSession); #ICICIC:
        # can we resume the session?
	unless (defined $myAppSession) {
            # NO! this time no exception, but undef returned (sic!)
	    $myAppSession = Session::GPMS::<MyApp>->create($masterSession) #ICICIC:
	}	
        # lookup the proect:
	my $project = $masterSession # only the GPMS-Session knows projects, a gpms session is
            -> getGPMSSubSession     # silently hidden in the masterSession
	    -> getApplicationFrame
            -> gpms_master->Project
	    -> init_arg($projectname);
	unless ($project) {
	    # there is no such project or so
	    # ICICIC: ERROR: no such project 
	    
	} else {
            # finally: 
	    $myAppSession->setProject($project);
	}
    }
  
    
    print more page output .... # ICICIC:
    
}

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.