Skip to content
This repository

a new OAI data provider in perl, based on T. Brody's HTTP::OAI

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 lib
Octocat-spinner-32 t
Octocat-spinner-32 Changes
Octocat-spinner-32 LICENSE
Octocat-spinner-32 MANIFEST
Octocat-spinner-32 META.json
Octocat-spinner-32 META.yml
Octocat-spinner-32 Makefile.PL
Octocat-spinner-32 README
Octocat-spinner-32 weaver.ini
README
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.

Something went wrong with that request. Please try again.