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. So expect some work.

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 is completely different from the old one, especially when it come to initialization of sessions. The only function that is unchanged is param, fortunately ;-) It can be used to get and set session parameters.

• The function params delivered all parameter values as key value pairs. This function does no longer exist. To replace it:
  • get all session parameters by using function getParams to get all parameter names
  • use param on each name and store the value
• There is no param_permanent any more, because you don't want it :-| If you do, blame Burkhard and suffer
• the function delete_param removes the param value, which was before done by setting the param to undef