GPMSWiki/DeveloperDocumentation/UsingApplicationFrame

Using an Application Frame

In addition to the standard classes of the GPMS we have implemented a general framework that simplifies the necessary steps for accessing a project's data. Such an Application Frame uses the GPMS for accessing the datasources of a project and it also provides a number of useful methods that are often needed by the end applications. The following description was directly included from the documentation of the Perl module. inputapplication_frame

Description

    An Application_Frame provides a general framework that
    simplifies using the General Project Management System
    (GPMS). It should be used for all O2DBI connections based on
    the GPMS (see documentation of O2DBI by B. Linke for further
    details about master objects etc.).

Concepts

    An Application_Frame acts as a container for all GPMS data
    that are required by an application for connecting to an
    O2DBI database. It provides access to:

    o a ProjectManagement master object
    o an application master object
    o a ProjectManagement::Project object
    o a ProjectManagement::User object
    o a ProjectManagement::Member object
    o the users password

    For using the Application_Frame a subclass has to be created
    that contains an application specific _init_application
    method, that provides the application master (see the
    documentation for _init_application for more detail).  The
    Application_Frame was initially introduced for some
    bioinformatics applications developed at Center for Genome
    Research, Bielefeld University. But it may be used as well
    with every other GPMS based application.

Methods

    o new($login, $passwd [,$gpms_master] [,$errh])
         Constructor, used for creating a new
         GPMS::Application_Frame object that provides the O2DBI
         master objects and all GPMS data relevant for an
         application. $errh is an optional error handler method,
         which is executed if an error occurs. As an argument
         $errh receives a string containing the error message.
         When $errh is specified it will be executed in every
         method called on the object whenever an error occurs.
         The optional argument $gpms_master is a
         ProjectManagement master object. It may be used when
         several Application_Frame objects are supposed to share
         the same GPMS master.

    o errh([$errh])
         Method used to get/set the error handler method. $errh
         is a reference on a subroutine that is executed if an
         error occurs. The only argument that is returned is the
         error message string.

    o login
         This method returns the login name of an user that was
         specified in the constructor method.

    o passwd
         The users password is required for establishing the
         connection to a database. Therefore the password is
         provided by this method.

    o gpms_master([$master])
         This method can be used to get/set the O2DBI master
         object for the GPMS.

    o application_master([$master])
         Get/set the O2DBI master object specific for the
         application or hash of O2DBI master objects if a
         project uses more than one database.

    o user
         Use this method to get the ProjectManagement::User
         object.

    o project([$project])
         This method can be used to get/set the project.
         $project can be a ProjectManagement::Project object or
         simply the name of a project.

    o get_available_projects($type)
         This method returns an array reference of all usable
         projects for the specified user. The type can be used
         to specify a subclass of ProjectManagement::Project
         (e.g. ProjectManagement::Project::GENDB).

    o user_name
         Get the full name of the current user.

    o user_email
         Get the email address of the current user.

    o error
         Default error method that can be used to get/set an
         error message if an error occured.

    o _init_application($project)
         This method has to be overloaded when a new subclass is
         created. The derived method can implement project
         specific initializations. It should always return an
         application master or a reference on a hash of
         application masters if a project uses more than one
         database. Since the Application_Frame is only
         applicable for projects using the second generation of
         the O2DBI tool other applications that use the old
         version by J. Clausen have to return 1 for successful
         connections or 0 if an error occured. The $project
         argument specifies a ProjectManagement::Project for
         which the Application_Frame should be initialized.

    o project_name
         Get the name of the project for which the
         Application_Frame was created.

    o project_description
         Get the description of the currently used project.

    o member([$member])
         Use this method to get/set the current member.

    o right($right_name)
         This method returns the value for a given project right
         for the current user.  Use this method to check the
         individual permissions (rights).

    o rights
         This method returns a reference on a hash of all
         project rights defined for the current user.

    o projectDB_by_datasource_!type_name($datasource_!type_name)
         Use this method to retrieve the database of a project
         for a specified datasource_type.

    o project_dbs
         This method returns a reference on an array of all
         databases in the current project.

    o project_datasources
         Use this method to retrieve a reference on an array of
         all available datasources for the current project.

    o user_project_config([$config])
         Use this method to get/set the complete project
         configurations for the current member of a project.
         $config is a hash of hash containing the configuration
         parameters and values for different configuration
         sections.

    o destroy
         Delete the Application_Frame object and clean up
         everything.

Author: Lutz Krause