Name

GUS::PluginMgr::Plugin


Description

GUS::PluginMgr::Plugin is the superclass of all GusApplication plugins.

Unless otherwise noted, all of its methods are instance methods. That is, they are called like this: $self->my_instance_method();


Methods

Constructor

new()
Construct a new Plugin. This method must be overridden by the plugin subclass. That is, the subclass must have its own new method which must:

- create and bless a $self

- call the initialize method described below

- return $self

Return type: hash ref

Initialization

initialize($argsHashRef)
Initialize the plugin. This method is called in the plugin's new method.

Parameters

- argsHashRef (hash ref). This argument is a hash ref which must contain the following key values pairs:

Setters

setResultDescr($resultDescrip)
Set the result description. This value is stored in the database in the AlgorithmInvocation table's result column after the plugin completes.

Params:

- resultDescrip: a description of the plugin's main result for posterity.

setPointerCacheSize()
The object cache holds 10000 objects by default. Use this method to change its capacity.

setOracleDateFormat($oracleDateFormat)
Set Oracle's NLS_DATE_FORMAT for the duration of this plugin's run. This is the format which oracle will allow for data of type 'Date.' See Oracle's documentation to find valid formats. The default format is 'YYYY-MM-DD HH24:MI:SS.'

Params:

- oracleDateFormat: a string specifying a valid Oracle date format

Getters

getUsage()
Get the plugin's usage. This value is set by the initialize method.

Return type: string

getDocumentation()
Get a hashref holding the plugin's documentation. This value is set by the initialize method.

Return type: string

getRequiredDbVersion()
Get the plugin's required database version. This value is set by the initialize method.

Return type: string

getCVSRevision()
Get the plugin's CVS revision number. This value is set by the initialize method.

Return type: string

getResultDescr
Get the result description.

Return type: string

getArgsDeclaration()
Get the plugin's argument declaration. This value is set by the initialize method.

Return type: ref_to_list_of_Args

getName()
Get the name of the plugin, eg, GUS::Supported::Plugin::LoadRow

Return type: string

getFile()
Get the full path of the file that contains the plugin, eg, /home/me/gushome/lib/perl/GUS/Supported/Plugin/LoadRow.pm

Return type: string

getArg($arg_name)
Get the value of one of the plugin's command line arguments.

Return type: scalar or list reference

getDb()
Get the DbiDatabase object which represents the database this plugin accesses.

Return type: GUS::ObjRelP::DbiDatabase

getAlgInvocation()
Get the AlgorithmInvocation which tracks the running of this plugin in the database.

Return type: GUS::Model::Core::AlgorithmInvocation

getQueryHandle()
Get the DbiDbHandle which this plugin uses to access the database.

Return type: GUS::ObjRelP::DbiDbHandle

getCheckSum()
Get an md5 digest checksum of the perl file which codes this plugin. (This is used by GusApplication when registering the plugin in the database.)

Return type: string

getAlgorithm()
Get the Algorithm that represents this plugin in the database.

Return type: GUS::Model::Core::Algorithm

getImplementation()
Get the AlgorithmImplementation that represents this version of this plugin in the database.

Return type: GUS::Model::Core::AlgorithmImplementation

Argument Declaration Constructors

The Argument Declaration Constructors return Argument Declaration objects, as expected by the initialize() method in its argDeclaration parameter. Each arg declaration object specifies the details of a command line argument expected by the plugin. The different constructors below are used to declare arguments of different types, such as string, int, file, etc.

The argument declaration constructor methods each take a hashref as their sole parameter. This hashref must include the required set of keys.

The following keys are standard and required for all the argument declaration constructors. (Additional non-standard keys are indicated below for each method as applicable.)

stringArg($argDescriptorHashRef)
Construct a string argument declaration.

Parameters

- argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above.

Return type: GUS::PluginMgr::Args::StringArg

integerArg($argDescriptorHashRef)
Construct a integer argument declaration.

Parameters

- argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above.

Return type: GUS::PluginMgr::Args::IntegerArg

booleanArg($argDescriptorHashRef)
Construct a boolean argument declaration.

Parameters

- argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above with the exception of 'isList' and 'constraintFunc', which are not applicable.

Return type: GUS::PluginMgr::Args::BooleanArg

tableNameArg($argDescriptorHashRef)
Construct a tableName argument declaration.

Parameters

- argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above.

Return type: GUS::PluginMgr::Args::TableNameArg

floatArg($argDescriptorHashRef)
Construct a float argument declaration.

Parameters

- argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above.

Return type: GUS::PluginMgr::Args::FloatArg

fileArg($argDescriptorHashRef)
Construct a file argument declaration.

Parameters

- argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above and also

over 4

  • mustExist (0 or 1)
  • Whether the file must exist

  • format (string)
  • A description of the file's format

    Return type: GUS::PluginMgr::Args::FileArg

    enumArg($argDescriptorHashRef)
    Construct an enum argument declaration.

    Parameters

    - argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above and also

    over 4

  • enum (a comma delimited list of terms)
  • The allowed values for this arugment

    Return type: GUS::PluginMgr::Args::EnumArg

    controlledVocabMapArg($argDescriptorHashRef)
    Construct a controlled vocab map argument declaration. The value for this argument is a file containing a mapping from an input set of terms to a set of terms in a GUS controlled vocabulary table (such as SRes.ReviewStatus). The value returned to the plugin by getArg() is that vocabulary in hash form, with the key being the input term and the value being the GUS term. If any GUS term in the file is not found in the database table, an error is thrown. This is used for application or site specific CVs, not for stable standards. It is intended to provide a flexible way for a plugin to use a CV developed in-house.

    Parameters

    - argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above and also

    over 4

  • table (a table name in SRes.ReviewStatus format)
  • The table in GUS in which this CV is stored

  • primaryKeyColumn (string)
  • The column in that table that holds its primary key

  • termColumn (string)
  • The column in that table that holds the CV term name

    Return type: GUS::PluginMgr::Args::ControlledVocabArg

    globArg($argDescriptorHashRef)
    Construct a glob argument declaration.

    Parameters

    - argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above and also

    over 4

  • mustExist (0 or 1)
  • Whether the glob must match some existing files.

  • format (string)
  • A description of the format of the files that match the glob.

    Return type: GUS::PluginMgr::Args::GlobArg

    globArg($argDescriptorHashRef)
    Construct a glob argument declaration.

    Parameters

    - argDescriptorHashRef (hash ref). This argument is a hash ref which must contain the standard keys described above and also

    over 4

  • mustExist (0 or 1)
  • Whether the glob must match some existing files.

  • format (string)
  • A description of the format of the files that match the glob.

    Return type: GUS::PluginMgr::Args::GlobArg

    Utilities

    className2oracleName($className)
    Convert a perl style class name for a database object to the form required in an SQL statement. For example, convert Core::Algorithm to core.algorithm

    Parameters:

    - className (string): A class name in the form: GUS::Model::Core::Algorithm or Core::Algorithm

    Return type: string

    getExtDbRlsId($dbName, $dbVersion)
    Retrieve an external database release id from SRes::ExternalDatabaseRelease given the name of a database and the version corresponding to the release.

    Die if none found. (If you just want to test for its existence, call the method in an eval{} block.)

    Parameters:

        - dbName (string): Name of the database; must match an entry in SRes::ExternalDatabase
        - dbVersion (string): Version of the database; matched against the version attribute in SRes::ExternalDatabaseRelease

    Return type: integer

    prepareAndExecute($sql)
    Prepare an SQL statement and execute it. This method is a convenience wrapper around $self->getQueryHandle()->prepareAndExecute(). In plugins, SQL is usually reserved for querying, not for writing to the database. GUS objects do that work with better tracking and more easily. For more complicated database operations see the file $PROJECT_HOME/OblRelP/lib/perl/DbiDbHandle.pm

    Parameters:

    - sql (string): The SQL to prepare and execute.

    Return type: statementHandle

    getControlledVocabMapping($cvMappingFile, $cvTable, $cvTermColumn)
    Read a file mapping input terms to a GUS CV. Validate the GUS CV against the provided table. If the GUS CV in the file is not entirely contained in the table, die. If it is, return the CV as a hash with the input terms as key and the GUS CV as value.

    Parameters:

    - cvMappingFile (string): The name of the file which contains the mapping. It must be two columns tab delimited where the first column is the input terms and the second column is the GUS CV.

    - cvTable (string): The name of the table in gus (in schema.table format) which contains the CV.

    - cvTermColumn (string): The name of the column in cvTable that contains the terms.

    Return type: hash reference

    getTotalInserts()
    Get the total number of inserts.

    getTotalUpdates()
    Get the total number of updates.

    className2TableId($className)
    Convert a perl style class name for a database object to a numerical table id suitable for comparison to one of GUS's many table_id columns. For example, convert Core::Algorithm to something like 34.

    Parameters:

    - className (string): A class name in the form: Core::Algorithm

    Return type: integer

    getFullTableClassName($className)
    If given a full class name or one in schema::table format (case insensitive in both cases), return the full class name w/ proper case, ie GUS::Model:Schema:Table or null if no such table

    Parameters: -

    - getFullTableClassName (string): A class name in the form: Core::Algorithm (case insensitive)

    Return type: string

    className2tableId($className)
    Convert a perl style class name for a database object to a numerical table id suitable for comparison to one of GUS's many table_id columns. For example, convert Core::Algorithm to something like 34.

    Parameters:

    - className (string): A class name in the form: Core::Algorithm (case sensitive)

    Return type: integer

    undefPointerCache()
    Clear out the GUS Object Layer's cache of database objects. The object cache holds 10000 objects by default. (You can change its capacity by calling $self->getDb()->setMaximumNumberOfObjects() >>.) Typically a plugin may loop over a set of input, using a number of objects for each iteration through the loop. Because the next time through the loop will not need those objects, it is good practice to call C<< $self->undefPointerCache() >> at the bottom of the loop to avoid filling the cache with objects that are not needed anymore.

    Documentation

    printDocumentationText($synopsis, $argDetails)
    Print documentation for this plugin in text format. The documentation includes a synopsis, description, and argument details

    Parameters

    - $synopsis (string): text providing a synopsis. - $argDetails (string): text providing details of the arguments.

    printDocumentationHTML($synopsis, $argDetails)
    Print documentation for this plugin in HTML format. The documentation includes a synopsis, description, and argument details

    Parameters

    - $synopsis (string): text providing a synopsis. - $argDetails (string): text providing details of the arguments.

    Error handling

    error($msg)
    Handle a fatal error in a plugin. This method terminates the plugin gracefully, writing the provided message to STDERR. It also writes a stack trace showing where the error occurred.

    When the plugin is terminated, GusApplication will still catch the error and attempt to track the plugin's failure in the database.

    Do not use this method to report user errors such as invalid argument values (use userError for that).

    Parameters

    - msg (string): the error message to write.

    userError($msg)
    Handle a fatal user error in a plugin. This method terminates the plugin gracefully, writing the provided message to STDERR. It it intended only for errors made by the user of the plugin (such as incorrect argument values).

    Parameters

    - msg (string): the error message to write.

    Logging

    log($msg1, $msg2, ...)
    Write a date stamped tab delimited message to STDERR. The messages supplied as arguments are joined with tabs in between.

    Parameters

    - @messages (list of strings): the error messages to write.

    logDebug($msg1, $msg2, ...)
    Write a date stamped tab delimited debugging message to STDERR. The messages supplied as arguments are joined with tabs in between. It will only be written if the user specifies the --debug argument.

    Parameters

    - @messages (list of strings): the error messages to write.

    logVerbose($msg1, $msg2, ...)
    Write a date stamped tab delimited debugging message to STDERR. The messages supplied as arguments are joined with tabs in between. It will only be written if the user specifies the --verbose argument.

    Parameters

    - @messages (list of strings): the error messages to write.

    logVeryVerbose($msg1, $msg2, ...)
    Write a date stamped tab delimited debugging message to STDERR. The messages supplied as arguments are joined with tabs in between. It will only be written if the user specifies the --veryVerbose argument.

    Parameters

    - @messages (list of strings): the error messages to write.

    logData($msg1, $msg2, ...)
    Write a date stamped tab delimited debugging message to STDOUT. The messages supplied as arguments are joined with tabs in between.

    Parameters

    - @messages (list of strings): the error messages to write.

    logAlgInvocationId()
    Log to STDERR the id for the AlgorithmInvocation that represents this run of the plugin in the database.

    logCommit()
    Log to STDERR the state of the commit flag for this run of the plugin.

    logArgs()
    Log to STDERR the argument values used for this run of the plugin.

    SQL utilities

    sql_get_as_array()
    Return type: string

    ()
    Return type: string

    ()
    Return type: string

    ()
    Return type: string

    sql_translate()
    Return type: string

    Deprecated

    getEasyCspOptions()
    Replaced by getArgsDeclaration()

    getRevisionNotes()
    No longer used.

    Return type: string

    getArgs()
    Replaced by getArg()

    getSelfInv()
    Replaced by getAlgInvocation

    getCla()
    Replaced by getArg

    logAlert()
    Replaced by log

    getOk()
    This method is replaced by the die/eval facilities of perl. Instead of using setOK(0), use die.

    setOk()
    This method is replaced by the die/eval facilities of perl. Instead of using getOK(), use eval.

    logRAIID()
    Replaced by logAlgInvocationId