OAI Provider
From DLXS Documentation
Main Page > Ancillary Resources > OAI Provider System
Contents |
Overview
Below you will find the documentation for using the UMProvider and the generic loading script (LoadOai.pl) used for loading data for the provider. These tools, along with the OAI Harvesting System, are available for download from Source Forge.
UMProvider
UMProvider: OAI-PMH 2.0 Provider Perl module. UMProvider requires that you have pre-formed oai_dc metadata in a database. The default database is mysql but any DBI.pm supported database should work. The data must be stored in two tables with the following required columns:
+----+-----------+--------+ | table: oai | | +----+-----------+--------+ | id | timestamp | oai_dc | +----+-----------+--------+ +----+-----------+ | table: oaisets | +----+-----------+ | id | oaiset | +----+-----------+
The second table for oai set information is optional just like the use of sets in OAI-PMH 2.0.
If you would like to provide additional metadata formats such as marc21 or mods add these columns after oai_dc in the first (main) table. The column name must match the metadata format. Here are example create table statements:
CREATE TABLE oai (id VARCHAR(20) PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
oai_dc MEDIUMBLOB,
marc21 MEDIUMBLOB);
CREATE TABLE oaisets (id VARCHAR(20),
oaiset VARCHAR(10);
The "id" values in the "oai" table and the "oaisets" tables must match. The id in the oai table must be unique but since an item can exist in multiple oai sets that id can repeat in the oaisets table. Records do not have to be assigned to a set so it is possible that an item in the oai table does not exist in the oaisets table.
IMPORTANT: If you have hierarchical sets, be sure to have an entry for each unique set name down to the root set for each item. For example, if the item "abc123" is in the set "foo:bar:baz", you should have the following three rows in the oaisets table:
+--------+-------------+ | id | oaiset | +--------+-------------+ | abc123 | foo:bar:baz | | abc123 | foo:bar | | abc123 | foo | +--------+-------------+
The id in the database is only the brief unique identifier and not the full OAI identifier. For the OAI-PMH response, the identifier is created with the host name (repositoryIdentifier) from the configuration file (oai:host:id).
Deleted records: If you would like to mark a record as deleted, just set the "oai_dc" field for that record to NULL in the database. The OaiProvider will continue to return the header for this record but the header will have the "deleted" status attribute.
Required perl modules: POSIX, XML::LibXML, DBI, Encode
Synopsis
Here is an example CGI script using UMProvider:
use OaiProvider;
use CGI;
use CGI::Carp;
my $query = CGI->new();
my @params = $query->param();
my $url = $query->url();
my $args = {};
foreach ( $query->param() ) { my @v = $query->param($_); $args->{$_} = "@v"; }
my $op = new OaiProvider(
configFile => "oai_provider_conf.xml",
logFile => "oai_provider.log",
url => $url,
arguments => $args);
if ( $op !~ /OaiProvider/ )
{
carp ($op);
print $query->header(-status => 500);
exit;
}
if ( ! $op->ConnectToDb( $db_user, $db_passwd, $db_name, $db_server ) )
{
carp ("failed ConnectToDb: $db_user, $db_passwd, $db_name, $db_server");
print $query->header(-status => 500);
exit;
}
$op->BuildResponse();
print $query->header(-type => ’text/xml’, -charset => ’utf-8’, -status => 200);
print $op->toString();
Available Methods
- new():
$op->new( hash_ref )
{ configFile => "oai_provider_conf.xml",
logFile => "oai_provider.log",
url => "http://some.url.org/OAI",
arguments => $args, ($args->{verb} = "ListSets")
## optional
maxItems => 500, ## default 100
tableName => "my_oai", ## default "oai"
setTableName => "my_oaisets", ## default "oaisets"
DBDriver => "SQLite", ## default "mysql"
DbUpdate => "2007-12-25 10:00:01", ## default to check update time of table
}
When the database table holding the OAI data is altered ('Update_time' changes for the table), any outstanding resumption tokens becomes invalid. If your data is constantly updated, or the OAI table is frequently updated for some reason other than data changes, use the optional "DbUpdate" time in your CGI script.
- ConnectToDb():
$op->ConnectToDb( $db_user, $db_passwd, $db_name, $db_server )
returns 0 if failed to connect to DB
- $op->BuildResponse()
Builds a response based on the cgi parameters passed in from new(). If a problem is found, an OAI error node is created and added to the response object
- $op->toString();
Serialize the response.
- $op->DisconnectDb();
The connection to the DB should be closed when the CGI script terminates. This may be useful if your CGI script is doing something else after getting the response.
Configuration
An XML configuration file must be passed to the UMProvider in new(). This file contains the information for the Identify verb, ListSets verb, and all possible metadataFormats (for ListMetadataFormats).
Sample config file:
<?xml version="1.0" encoding="UTF-8"?>
<oai_config>
<Identify>
<repositoryName>Your Repository</repositoryName>
<baseURL>http://your.host.edu/OAI</baseURL>
<protocolVersion>2.0</protocolVersion>
<adminEmail>you@your.edu</adminEmail>
<earliestDatestamp/>
<deletedRecord>transient</deletedRecord>
<granularity>YYYY-MM-DDThh:mm:ssZ</granularity>
<description>
<oai-identifier xmlns="http://www.openarchives.org/OAI/2.0/oai-identifier"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai-identifier
http://www.openarchives.org/OAI/2.0/oai-identifier.xsd">
<scheme>oai</scheme>
<repositoryIdentifier>your.host.edu</repositoryIdentifier>
<delimiter>:</delimiter>
<sampleIdentifier>oai:your.host.edu:000000001</sampleIdentifier>
</oai-identifier>
</description>
</Identify>
<ListSets>
<set>
<setSpec>foo</setSpec>
<setName>All things of foo</setName>
</set>
<set>
<setSpec>bar</setSpec>
<setName>All things of bar</setName>
</set>
</ListSets>
<PossibleMetadataFormats>
<metadataFormat>
<metadataPrefix>oai_dc</metadataPrefix>
<schema>http://www.openarchives.org/OAI/2.0/oai_dc.xsd</schema>
<metadataNamespace>http://www.openarchives.org/OAI/2.0/oai_dc</metadataNamespace>
</metadataFormat>
<metadataFormat>
<metadataPrefix>marc21</metadataPrefix>
<schema>http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd</schema>
<metadataNamespace>http://www.loc.gov/MARC21/slim</metadataNamespace>
</metadataFormat>
</PossibleMetadataFormats>
</oai_config>
LoadOai.pl
This script looks for XML files in the data dir and loads each record into the oai and oaisets DB tables. Before using you must change the DB connection settings at the top of this script:
my $dbUser = "user"; my $dbPasswd = "passwd"; my $dbName = "foo"; my $dbServer = "bar";
The available arguments for the script are:
-d data dir (place to find the XML data) -s oai set (optional) -h (help: message printed) -v (generates verbose output which is stored in the loading Log)
The only required arguments are the data dir (-d).
All of the data within and including the <metadata> element is loaded into the DB under the specified format. This data is not validated or checked in any way other than to make sure it is well formed XML.
If the oai set (-s) is used, the setSpec is not checked in the /record/header/ element.
For the identifier, the script only cares about everything after the last ":" (oai:host:id).
- DB format (see above under UMProvider)
- XML Format
The XML files must have the OAI record elements wrapped in a <records> element. By default, this script will look for record elements wrapped in a <records> tag. If you have the data nested some other way, just change $recordXpath to the correct xpath to find the record elements. There can be multiple record elements in a single file as well as multiple ".xml" files in the data directory. Here’s an example XML file:
<?xml version="1.0" encoding="UTF-8"?>
<records>
<record>
<header>
<identifier>oai:some.host..edu:id-1234</identifier>
<datestamp>2007-10-22T15:43:11Z</datestamp>
<setSpec>foo</setSpec>
</header>
<metadata> [ ... ]
</metadata>
</record>
<record> [ ... ] </record>
</records>
