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.

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

getCVSTag()
Get the plugin's CVS tag. This value is set by the initialize method.

Return type: string

getRevisionNotes()
Get the plugin's revision notes. This value is set by the initialize method.

Return type: string

getEasyCspOptions()
Get the plugin's EasyCsp options. This value is set by the initialize method.

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::Common::Plugin::UpdateRow

Return type: string

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

Return type: string

getArgs()
Get the plugin's command line arguments. To access these within the plugin, use: $self->getArgs()->{arg_name}.

Return type: Hash 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)
    The a description of the file's format

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

  • 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

    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 $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.

    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

    ()
    Return type: string

    Deprecated

    getSelfInv()
    Replaced by getAlgInvocation

    getCla()
    Replaced by getArgs

    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