Skip to content


Subversion checkout URL

You can clone with
Download ZIP
a new OAI data provider in perl, based on T. Brody's HTTP::OAI


    HTTP::OAI::DataProvider - A simple OAI data provider

    version 0.009

            #(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;

            if ($provider->error) {         
                    my $response=$provider->OAIerrors;
                    my $xml=$provider->asString($response);

    This package implements an OAI data provider according to

    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/ and a command line
    interface (bin/

  my $provider->new ($options);
    Initialize the HTTP::OAI::DataProvider object with the options of your

    On failure return nothing.

   Identify Parameters
    expects a hashref with key value pairs inside all of which are required:

            identify => {
                    adminEmail     => '',
                    baseURL        => 'http://localhost:3000/oai',
                    deletedRecord  => 'transient',
                    repositoryName => 'test config OAI Data Provider',

    See OAI specification (Identify) for available options and other

   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 => "",
                            ns_schema =>
                    oai_dc => {
                            ns_uri    => "",
                            ns_schema => "",

   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
            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 *

  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


    *   identifier (optional)


    *   badArgument - in validate_request()

    *   idDoesNotExist - here

    *   noMetadataFormats - here

  my $response=$provider->ListIdentifiers (%params);

    *   from (optional, UTCdatetime value)

    *   until (optional, UTCdatetime value)

    *   metadataPrefix (required)

    *   set (optional)

    *   resumptionToken (exclusive)


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


    *   from (optional, UTCdatetime value)

    *   until (optional, UTCdatetime value)

    *   metadataPrefix (required unless resumptionToken)

    *   set (optional)

    *   resumptionToken (exclusive)


    *   badArgument

    *   badResumptionToken

    *   cannotDisseminateFormat

    *   noRecordsMatch

    *   noSetHierarchy - TODO

  my $response=$provider->ListSets(%params);

    *   resumptionToken (optional)


    *   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

            $provider->checkFormatSupported( $prefix );
            if ($provider->error) {
                    #do something
            $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.

    Have errors occured? Returns number of errors that have been added to
    error stack so far or else false.

    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,

            my $response=$provider->verb(%params);

    Tim Brody's HTTP::OAI
    Jeff Young's (OCLC) OAICAT (java) at

    Maurice Mengel <>

    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.

Something went wrong with that request. Please try again.