NAME
HTTP::OAI::DataProvider - A simple OAI data provider
VERSION
version 0.009
SYNOPSIS
#(1) Init
use HTTP::OAI::DataProvider;
my $provider = HTTP::OAI::DataProvider->new(%options);
#(2) Verbs: GetRecord, Identify ...
my $response=$provider->$verb(%params);
my $xml=$provider->asString($response);
my $xml=$provider->asString($response);
#$response is a HTTP::OAI::Response object (verbs or error)
#(3) NEW ERROR HANDLING
my $response=$provider->addError(code=>'badArgument');
if (!$provider->validateRequest (%params));
my $response=$provider->OAIerrors;
}
#elsewhere
if ($provider->error) {
my $response=$provider->OAIerrors;
my $xml=$provider->asString($response);
$provider->resetErrorStack;
}
DESCRIPTION
This package implements an OAI data provider according to
<http://www.openarchives.org/OAI/openarchivesprotocol.html>
The provider is database and metadata format agnostic. It comes with
simple example implementations that should work out of the box,
including an SQLite backend (DP::Engine::SQLite), a metadata format
(DP::Mapping::MPX), web interface (bin/webapp.pl) and a command line
interface (bin/dp.pl).
METHODS
my $provider->new ($options);
Initialize the HTTP::OAI::DataProvider object with the options of your
choice.
On failure return nothing.
Identify Parameters
expects a hashref with key value pairs inside all of which are required:
identify => {
adminEmail => 'mauricemengel@gmail.com',
baseURL => 'http://localhost:3000/oai',
deletedRecord => 'transient',
repositoryName => 'test config OAI Data Provider',
},
See OAI specification (Identify) for available options and other
details.
Engine Parameters
engine->{engine} specifies the engine you use. Other parameters depend
on the engine you use. All engine parameters are handed down to the
engine you use.
engine => {
engine => 'HTTP::OAI::DataProvider::Engine::SQLite',
moreParameters => 'see your engine for more info on those params',
},
Message Parameters
debug => sub { my $msg = shift; print "<<$msg\n" if $msg; },
warning => sub { my $msg = shift; warn ">>$msg" if $msg; },
Metadata Format Parameters
globalFormats => {
mpx => {
ns_uri => "http://www.mpx.org/mpx",
ns_schema =>
"http://github.com/mokko/MPX/raw/master/latest/mpx.xsd",
},
oai_dc => {
ns_uri => "http://www.openarchives.org/OAI/2.0/oai_dc/",
ns_schema => "http://www.openarchives.org/OAI/2.0/oai_dc.xsd",
},
},
Set Parameters
setLibrary => {
'78' => {
'setName' => 'Schellackplatten aus dem Phonogramm-Archiv'
},
'MIMO' =>
{ 'setName' => 'Musical Instruments selected for MIMO project' },
'test' => {
'setName' => 'testing setSpecs - might not work without this one',
},
},
Other Parameters (Optional)
xslt => '/oai2.xsl',
Adds path to HTTP::OAI::Repsonse objects to modify output in browser.
requestURL => 'http://bla.url'
Overwrite normal requestURL, e.g. when using a reverse proxy etc.
Note that requestURL specified during new is only the http://domain.com:port
part (without ? followed by GET params), but that HTTP::OAI treats the
complete URL as requestURL
my $result=$provider->_GetRecord(%params);
Arguments =for :list * identifier (required) * metadataPrefix (required)
Errors =for :list * badArgument * cannotDisseminateFormat *
idDoesNotExist
my $response=$provider->Identify([%params]);
Arguments: none
Errors: badArgument
The information for the identify response is assembled from two sources:
from configuration during new and from inspection of the system
(earlierstDate, granularity).
ListMetadataFormats (%params);
"This verb is used to retrieve the metadata formats available from a
repository. An optional argument restricts the request to the formats
available for a specific item." (the spec)
HTTP::OAI::DataProvider only knows global metadata formats, i.e. it
assumes that every record is available in every format supported by the
repository.
ARGUMENTS
* identifier (optional)
ERRORS
* badArgument - in validate_request()
* idDoesNotExist - here
* noMetadataFormats - here
my $response=$provider->ListIdentifiers (%params);
ARGUMENTS
* from (optional, UTCdatetime value)
* until (optional, UTCdatetime value)
* metadataPrefix (required)
* set (optional)
* resumptionToken (exclusive)
ERRORS
* badArgument
* badResumptionToken
* cannotDisseminateFormat
* noRecordsMatch
* noSetHierarchy
NOTE Depending on the repository's support for deletions, a returned
header may have a status attribute of "deleted" if a record matching the
arguments specified in the request has been deleted.
LIMITATIONS By making the metadataPrefix required, the specification
suggests that ListIdentifiers returns different sets of headers
depending on which metadataPrefix is chose. HTTP:OAI::DataProvider
assumes, however, that there are only global metadata formats, so it
will return the same set for all supported metadataFormats.
TODO: Hierarchical sets
my $response=$provider->ListRecords(%params);
returns multiple items (headers plus records) at once. In its capacity
to return multiple objects it is similar to the other list verbs
(ListIdentifiers). ListRecord also has the same arguments as
ListIdentifier. In its capacity to return full records (incl. header),
ListRecords is similar to GetRecord.
ARGUMENTS
* from (optional, UTCdatetime value)
* until (optional, UTCdatetime value)
* metadataPrefix (required unless resumptionToken)
* set (optional)
* resumptionToken (exclusive)
ERRORS
* badArgument
* badResumptionToken
* cannotDisseminateFormat
* noRecordsMatch
* noSetHierarchy - TODO
my $response=$provider->ListSets(%params);
ARGUMENTS
* resumptionToken (optional)
ERRORS
* badArgument
* badResumptionToken
* noSetHierarchy
checkFormatSupported ($prefixWanted);
Expects a metadata prefix (as scalar). If it can't be disseminated an
OAI error is added to OAIerror stack and checkFormatSupported return 0
(fail). If format is supported, it returns 1 (success) and sets no
error.
#Either
$provider->checkFormatSupported( $prefix );
if ($provider->error) {
#do something
}
#Or
$provider->checkFormatSupported( $prefix ) or return $self->OAIerror;
my $xml=$self->asString($response);
Expects a HTTP::OAI::Response object and returns it as xml string. It
applies $self->{xslt} if set and also applies a current requestURL.
$self->error
Have errors occured? Returns number of errors that have been added to
error stack so far or else false.
$provider->resetErrorStack;
Creates a new empty HTTP::OAI::Response for OAIerrors.
I wonder if this should be called before every verb. Then I probably
don't need to call it from the outside at all.
$self->validateRequest(%params) or return $self->OAIerrors;
Expects params in hash. It saves potential errors in $provider->errorOAI
and returns 1 on success (i.e. no validation error) or fails when
validation showed an error.
$self->addError(code=>$code, message=>$message);
Expected is an error code and optionally an error message. If not
specified, message will use default message for that error code. Returns
a HTTP::OAI::Response object with the error stack. Croaks on failure.
TODO: Theoretically, I need a way to add multiple errors at once:
$self->addError([(code=>$code, message=>$message), (code=>$code,
message=>$message)]);
verb
my $response=$provider->verb(%params);
SEE ALSO
<http://www.openarchives.org/OAI/openarchivesprotocol.html>
Tim Brody's HTTP::OAI
Jeff Young's (OCLC) OAICAT (java) at
<http://www.oclc.org/research/activities/oaicat/>
AUTHOR
Maurice Mengel <mauricemengel@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Maurice Mengel.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
mokko/HTTP-OAI-DataProvider
a new OAI data provider in perl, based on T. Brody's HTTP::OAI
PerlNOASSERTION