World-2DPAGE Home
 

DbCrossRefs.pm


NAME

DbCrossRefs.pm (0.04.1) - A Perl module to manage cross-reference database links

SYNOPSIS


use DbCrossRefs;



$db_object = new DbCrossRefs;



$db_object->open("database_file.db", "db");



$url_link = $db_object->get("SOME_DATABASE", "$ac", "$second_id") 

  if $db_object->check("SOME_DATABASE");



$db_object->add("NEW_DATABASE", "http://www.somewhere.org/displayer?ac={0}&sp={1}") 

  unless $db_object->exists("NEW_DATABASE");



$db_object->commit;



$db_object->export_file("database.txt", "txt");



%db_refs = $db_object->get_all();



$linkValidator = $db_object->check();



$db_object = undef;

        

DESCRIPTION

DbCrossRefs.pm provides methods to :



- create, manage and read files listing cross-reference database links in both text and DBM format

- check for the availability of the links

- export and import files

EXCEPTIONS

exceptions are confessed (for failed calls / invalid or missing arguments)

or warned (for data dependant conflicts)

METHODS


$db_object = new DbCrossRefs ([file_name] [, file_format = {"txt" | db"}])

Constructor:
    Creates a new object and opens an already existing or a not existing yet file for future operations if file_name is given. The file_format determines which type of file to open and work with (either "txt" for text files, or "db" for DBM database files). If not given, file_format is "txt" by default.
Alternative:
    By default, databases names are case sensitive. In order to work with case insensitivity, create your new object with: $db_object = new DbCrossRefs("case_insensitive") Then use the "open" method to open your file. Tip: use the "export_file" method rather than the "commit" method to preserve case sensitivity in your original file.

$db_object->open ([file_name [, file_format = {"txt" | "db"}]])

Purpose:
    Opens an already existing or a not existing yet file for future operations if file_name is given. The file_format determines which type of file to open and work with (either "txt" for text files, or "db" for DBM database files).  If no argument is given, a temporary file is used instead. This method is required to execute any subsequent method, and it always overrides its own previous value. If file_name exists, all databases that it contains are loaded into the current databases list.
Returns:
  • 1 if it succeeds
  • confess exception if not

$db_object->add (database, url [, comment] [, check= 1])

Purpose:
    Adds an new database with its corresponding url to the current databases list. The database name should not include spaces. It will be converted to lower case if the "case_insensitive" flag is activated. The url should point to an approriate URL to display entries from this database. To be able to pass GET arguments to this URL, include into the GET string incremental values between braces. Start from '0' to as many parameters as you wish. e.g.
    "http://www.somewhere/cgi-bin/some_displayer?accession_number={0}&species={1}"
    Any parameter may be given a default value by following it's number with colons and an existing identifier. Those identifiers will then be used to check if the URL is valid (in conjunction with the 'cehck' method), e.g.
    "http://www.somewhere/cgi-bin/some_displayer?accession_number={0:P12345}&species={1:9604}"
    Comments are free text and will be automatically prefixed by a '#' sign followed by the database name between brackets. In DBM format, all comments will be grouped together and will share the same common key ( "_comment_").
    If you define a fourth parameter (e.g check set to 1), the url you provide will be checked first via a HTTP connection before it is allowed to be added.
Returns:
  • 1 if it succeeds to add database
  • undef if it fails, if no file has been opened or if database already exists
  • confess exception for missing / wrong arguments

$db_object->alter (database, new_url [, comment] [, check = 1])

Purpose:
    Changes the current URL of an already existing database to new_url (see the 'add' method for a description of URL syntax).
Returns:
  • 1 if it succeeds
  • undef if it fails or if no file has been opened
  • confess exception for missing / wrong arguments

$db_object->alter_name (old_database_name, new_database_name)

Purpose:
    Chenges a database name  (old_database_name) to new_database_name.
Returns:
  • 1 if it succeeds
  • undef if it fails or if no file has been opened
  • confess exception for missing arguments

$db_object->delete (database)

Purpose:
    Deletes a database from the current list.
Returns:
  • 1 if it succeeds
  • 0 if no database with this name could be found
  • undef if no file has been opened
  • confess exception for missing /wrong arguments

$db_object->exists (database_1 [, database_2] ... [, database_n])

Purpose:
    Checks if one or several databases exist already in the current list
Returns:
  • 1 if all the databases exist
  • 0 if one or more databases do not exist
  • undef if no file has been opened
  • confess exception for missing / wrong arguments

$db_object->get (database [, identifier_1] [, identifier_2] ... [, identifier_n])

Purpose:
    Gets the URL corresponding to an already existing database. Identifiers will be inserted into the arguemnt string in replacement of the corresponding '{n-1}' substring. e.g. (cf. the $db_object->add method)
    $url = $db_object->get("SOME_DATABASE", "P12345", "12000");
    print $url;
    =>
    http://www.somewhere/cgi-bin/some_displayer?accession_number=P12345&species=12000
Returns:
  • a string if succeeds
  • undef if it fails or if no file has been opened
  • confess exception for wrong arguments

$db_object->get_all ([format = {"txt"}], [expression])

Purpose:
    Gets a list of all databases in the current list. If no argument is given, a hash is sent with databases names for keys and URLs for values. If a "txt" format is requested, a string of several lines is sent, each line beginning with a database name, followed by a space, and ending with the corresponding URL. You can limit your query to list databases that contain 'expression' in their name by defining a second argument (search will be case insensitive).
Returns:
  • a hash if no argument is given
  • a string if "txt" is given as argument
  • undef if no file has been opened
  • confess exception for missing / wrong arguments

$db_object->get_comment ([expression_1] ... [, expression_n]))

Purpose:
    Gets all comments (if no argument) or comments containing any of the arguments (usually database names).
Returns:
  • a string it succeeds
  • undef if expressions are not alphanumerical or if no file has been opened

$db_object->check ([database_1] ... [, database_n])

Purpose:
    Checks for the vailidity of the URLs for all the databases included in the current list (when no argument is specified). The checking is limited to the specified databases if they are given as arguments. Many URLs would require some existing identifiers in their GET string to be correctly checked. Refer to the 'add' method on how to add default identifiers.
Returns:
  • a void string if all databases URLs have been checked with success
  • a non void string containig HTTP connection errors if one or more databases failed to connect correctly
  • undef if Perl is lower than 5.005 version or if no file has been opened

$db_object->import_file (file_name [, file_format = {"txt" | db"}])

Purpose:
    Imports databases and their corresponding URLs an d comments from an existing file to the current databases list. If file_format is not given, the format is supposed to be "txt" (cf. the <open> method for more details)
Returns:
  • 1 if it succeeds
  • undef if it fails or if no file has been opened
  • confess exception for missing / wrong arguments

$db_object->export_file (file_name [, file_format = {"txt" | db"}])

Purpose:
    Exports databases and their corresponding URLs and comments from the current databases list to a new file. If file_format is not given, the format is supposed to be "txt" (cf. the <open> method for more details).
Returns:
  • 1 if it succeeds
  • undef if it fails or if no file has been opened
  • confess exception for missing / wrong arguments

$db_object->reset ()

Purpose:
    Resets the current lists to its initial state as it was just after the last invoked <open> method. All modifications or additions applied to this list will be definitively lost.
Returns:
  • 1 if it succeeds
  • undef for wrong arguments or if no file has been opened

$db_object->commit ([file_name [, file_format = {"txt"|"db"}]])

Purpose:
    No changes are saved into the original file before invoking this method. When called, this method saves physically the current databases list, with all the applied modifications and additions, to the initial file given with the <open> method. If file_name is specifeid, the list will be saved in this file instead of the initial opened one. file_name is also required if the <open>  method has been invoked without a file name argument.
Returns:
  • 1 if it succeeds
  • undef if it fails or if no file has been opened
  • confess exception for missing arguments

$db_object = undef

Purpose:
    Destroy object.

OVERRIDDEN METHODS (when using Expasy.pm on the ExPASy servers)

warn($message)

from :  perlfunc
action :  Writes the error message and the stack trace into $GL_logs/cgi_log and an e-mail message sent to http@hostname no more than every 30 minutes (or 2 hours during the night and weekend GMT).
overrides :  warn() [which can still be called with CORE::warn()]

NOTES

This module uses the mechanism of exceptions (confession), which are thrown from the calling routine up the stack trace and cause a die() unless caught. Therefore, methods which throw exceptions maybe be called within an eval{} block. The special variable $@ can then be checked for an error message.

AUTHOR

Khaled Mostaguir (khaled.mostaguir@isb-sib.ch)