Classes and their functions

Classes and their functions
Prev	Chapter 20. The Perl client module	Next

Like most Perl modules, the RefDBClient::Client module is object-oriented. This section introduces the two classes that you need to know in order to work with the module. To see a working example, please check the test.pl script shipped with the module.

The main class that is used to access all RefDB client functions is called RefDBClient::Client. To get started, create a new instance and set the communication parameters:

use RefDBClient::Client;

my $client = new RefDBClient::Client;

$client->set_conninfo("127.0.0.1", "9734", "markus", "pass", "refdbtest",
                      "/home/markus/literature", "/usr/local/share/refdb/css/refdb.css", "360");

Then you can go ahead and send commands to the server like this:

$summary = $client->refdb_listdb("");
$data = $client->get_data();

Note

As you can easily guess the functions implementing the client commands are analogous to the commands found in the refdba and refdbc clients. See the reference pages about these apps for further information about the commands.

There are three helper classes:

RefDBClient::Risdata provides a simple interface to RIS data
ReFDBClient::Simplelist is used internally
RefDBClient::Enigma handles the password encryption

RefDBClient::Risdata

new

new RefDBClient::Risdata( void);

Creates a new Risdata object

read_ris

$data->read_ris( $file);

loads RIS data from a file

$file: path of file

get_ris

$data->get_ris( void);

returns previously loaded RIS data

RefDBClient::Simplelist

new

new RefDBClient::Simplelist( void);

creates a new Simplelist element

RefDBClient::Enigma

new

new RefDBClient::Enigma( void);

creates a new Enigma element

RefDBClient::Client

new

new RefDBClient::Client( void);

creates a new Client element

set_conninfo

`$client->set_conninfo(`		`$server_ip`,
		`$port_address`,
		`$username`,
		`$password`,
		`$database`,
		`$pdf_root`,
		`$css_url`,
		`$timeout)`;

sets the initial connection parameters of a Client object

$server_ip: IP address or hostname of the server that runs refdbd
$port_address: Port address at which refdbd listens
$username: Username for database password authentication
$password: Password for database password authentication
$database: Name of the reference database
$pdf_root: Path of the root directory of all electronic offprints
$css_url: URL of a Cascading Stylesheets file for (X)HTML output
$timeout: Timeout in seconds after which a stale connection is taken down

get_status

$client->get_status( void);

returns the numerical server status

get_status_msg

$client->get_status_msg( void);

returns the server status message

get_data

$client->get_data( void);

returns the data of the most recent command

get_summary

$client->get_summary( void);

returns the summary of the most recent command

refdb_addstyle

$client->refdb_addstyle( $styledata);

adds a citation/bibliography style to the database

$styledata: XML data representing the bibliography style

refdb_adduser

`$client->refdb_adduser(`		`$host`,
		`$database`,
		`$newuserpassword`,
		`$username)`;

adds new users to the database

$host: host specification from which the user is allowed to connect
$database: name of the reference database
$newuserpassword: password (required only for new users)
$username: name of the user, as used to authenticate at the database engine

refdb_deleteuser

`$client->refdb_deleteuser(`		`$host`,
		`$database`,
		`$username)`;

deletes users from the database

$host: host specification from which the user is allowed to connect
$database: name of the reference database
$username: name of the user, as used to authenticate at the database engine

refdb_addword

$client->refdb_addword( $words);

adds reserved words to the main database

$words: space-separated list of words

refdb_deleteword

$summary = $client->refdb_deleteword( $words);

removes reserved words from the main database

$words: space-separated list of words

refdb_confserv

$client->refdb_confserv( $command);

sends a configuration command to the server

$command: the command proper, optionally followed by an argument

refdb_createdb

`$client->refdb_createdb(`		`$dbname`,
		`$encoding)`;

creates a new database

$dbname: name of the reference database
$encoding: character encoding

refdb_deletedb

$client->refdb_deletedb( $databasename);

deletes a reference database

$dbname: name of the database

refdb_deletestyle

$client->refdb_deletestyle( $stylename_regexp);

deletes citation/bibliography styles

$stylename_regexp: regular expression describing the names of the styles to be deleted

refdb_getstyle

$client->refdb_getstyle( $stylename);

retrieves a citation/bibliography style as a citestylex doc

$stylename: name of the style

refdb_listdb

$client->refdb_listdb( $dbname_regexp);

lists matching databases

$dbname_regexp: regular expression describing the database names

refdb_listuser

`$client->refdb_listuser(`		`$dbname`,
		`$username_regexp)`;

lists matching user names

$username_regexp: regular expression describing the user names

refdb_listword

$client->refdb_listword( $word_regexp);

lists matching journal name words

$wordname_regexp: regular expression describing the word names

refdb_liststyle

$client->refdb_liststyle( $stylename_regexp);

lists matching citation/bibliography styles

$stylename_regexp: regular expression describing the style names

refdb_viewstat

$client->refdb_viewstat( void);

requests version/connection info from the server

refdb_scankw

$client->refdb_scankw( $dbname);

runs a thorough keyword scan in the given database

$dbname: name of the reference database

refdb_addref

`$client->refdb_addref(`		`$owner`,
		`$refdata`,
		`$type`,
		`$encoding)`;

adds references to the database

$owner: name of the dataset owner, if different from current user
$refdata: string containing the reference data
$type: data type, must be one of 'ris' or 'risx'
$encoding: character encoding of the input data (only for RIS data)

refdb_checkref

`$client->refdb_checkref(`		`$risdata`,
		`$type`,
		`$encoding`,
		`$outtype)`;

Checks new references against the references in the database without adding them permanently

$risdata: string containing the reference data
$type: data type, must be one of 'ris' or 'risx'
$encoding: character encoding of the input data (only for RIS data)
$outtype: output data type, must be one of 'scrn' or 'xhtml'

refdb_updateref

`$client->refdb_updateref(`		`$owner`,
		`$is_personal`,
		`$risdata`,
		`$type`,
		`$encoding)`;

updates references in the database

$owner: name of the dataset owner, if different from current user
$is_personal: set to 't' if only the personal information shall be updated
$refdata: string containing the reference data
$type: data type, must be one of 'ris' or 'risx'
$encoding: character encoding of the input data (only for RIS data)

refdb_deleteref

$client->refdb_deleteref( $idlist);

deletes references from the database

$idlist: string specifying the IDs of the references to be deleted

refdb_addnote

`$client->refdb_addnote(`		`$owner`,
		`$xnotedata)`;

adds notes to the database

$owner: owner of the note, if different from the current user
$xnotedata: XML data specifying the note

refdb_updatenote

`$client->refdb_updatenote(`		`$owner`,
		`$is_personal`,
		`$xnotedata)`;

updates references in the database

$owner: owner of the note, if different from the current user
$is_personal: set to 't' if only the personal information shall be updated
$xnotedata: XML data specifying the note

refdb_deletenote

$client->refdb_deletenote( $idlist);

deletes notes from the database

$idlist: string specifying the ID values of the notes to be deleted

refdb_addlink

$client->refdb_addlink( $linkspec);

links notes to database objects

$linkspec: string specifying the link(s) to be created

refdb_deletelink

$client->refdb_deletelink( $linkspec);

unlinks notes from database objects

$linkspec: string specifying the link(s) to be deleted

refdb_getas

`$client->refdb_getas(`		`$limit_string`,
		`$name_regexp)`;

retrieves matching series authors

$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_getau

`$client->refdb_getau(`		`$limit_string`,
		`$name_regexp)`;

retrieves matching authors

$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_geted

`$client->refdb_geted(`		`$limit_string`,
		`$name_regexp)`;

retrieves matching editors

$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_getkw

`$client->refdb_getkw(`		`$limit_string`,
		`$keyword_regexp)`;

retrieves matching keywords

$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$keyword_regexp: regular expression describing the keywords to be retrieved

refdb_getjf

`$client->refdb_getjf(`		`$is_all`,
		`$limit_string`,
		`$journal_regexp)`;

retrieves matching periodicals (full names)

$is_all: set to 't' if all synonymous journal names shall be returned
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_getjo

`$client->refdb_getjo(`		`$is_all`,
		`$limit_string`,
		`$journal_regexp)`;

retrieves matching periodical names (abbrev)

$is_all: set to 't' if all synonymous journal names shall be returned
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_getj1

`$client->refdb_getj1(`		`$is_all`,
		`$limit_string`,
		`$journal_regexp)`;

retrieves matching periodical names (custom abbrev 1)

$is_all: set to 't' if all synonymous journal names shall be returned
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_getj2

`$client->refdb_getj2(`		`$is_all`,
		`$limit_string`,
		`$journal_regexp)`;

retrieves matching periodical names (custom abbrev 2)

$is_all: set to 't' if all synonymous journal names shall be returned
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$name_regexp: regular expression describing the names to be retrieved

refdb_getref

`$client->refdb_getref(`		`$type`,
		`$format_string`,
		`$sort_string`,
		`$listname`,
		`$encoding`,
		`$limit_string`,
		`$query_string)`;

retrieves references

$type: select output format
$format_string: specify additional fields to be retrieved
$sort_string: specify sorting key
$listname: specify a list name if the search is to be confined to a particular personal reference list
$encoding: the character encoding for the output data
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$query_string: the query that describes the datasets to be retrieved

refdb_countref

`$client->refdb_countref(`		`$listname`,
		`$limit_string`,
		`$query_string)`;

Counts matching references

$listname: specify a list name if the search is to be confined to a particular personal reference list
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$query_string: the query that describes the datasets to be counted

refdb_pickref

$client->refdb_pickref( $idlist$listname);

adds references to the users personal reference list

$idlist: specifies the ID values of the references to be picked
$listname: the name of the personal list that the references should be added to. If this string is empty, the default personal list is used instead,

refdb_dumpref

$client->refdb_dumpref( $idlist$listname);

removes references from personal reference list

$idlist: specifies the ID values of the references to be dumped
$listname: the name of the personal list that the references should be added to. If this string is empty, the default personal list is used instead,

refdb_getnote

`$client->refdb_getnote(`		`$type`,
		`$format_string`,
		`$sort_string`,
		`$encoding`,
		`$limit_string`,
		`$query_string)`;

retrieves references

$type: select output format
$format_string: specify additional fields to be retrieved
$sort_string: specify sorting key
$encoding: the character encoding for the output data
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$query_string: the query that describes the datasets to be retrieved

refdb_countnote

`$client->refdb_countnote(`		`$listname`,
		`$limit_string`,
		`$query_string)`;

Counts matching extended notes

$listname: specify a list name if the search is to be confined to a particular personal reference list
$limit_string: Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.
$query_string: the query that describes the datasets to be counted

refdb_selectdb

$client->refdb_selectdb( $dbname);

selects an existing database as the current database

$dbname: name of the reference database

refdb_whichdb

$client->refdb_whichdb( void);

displays information about the current database

refdb_texbib

`$client->refdb_texbib(`		`$style`,
		`$cite_data)`;

retrieves a bibliography in bibtex format based on citationlistx data

$style: the name of the citation/bibliography style
$cite_data: XML data describing the references

refdb_dbib

`$client->refdb_dbib(`		`$type`,
		`$style`,
		`$encoding`,
		`$cite_data)`;

retrieves an XML/SGML bibliography based on citationlistx data

$type: type of the bibliography output
$style: name of the citation/bibliography style
$encoding: character encoding of the output data
$cite_data: XML data specifying the references