NAME

Plack::App::Catmandu::OAI - drop in replacement for Dancer::Plugin::Catmandu::OAI

SYNOPSIS

    use Plack::Builder;
    Plack::App::Catmandu::OAI;

    builder {
        enable 'ReverseProxy';
        enable '+Dancer::Middleware::Rebase', base  => Catmandu->config->{uri_base}, strip => 1;
        mount "/oai" => Plack::App::Catmandu::OAI->new(
            repositoryName => 'my repo',
            store => 'search',
            bag   => 'publication',
            cql_filter => 'type = dataset',
            limit  => 100,
            datestamp_field => 'date_updated',
            deleted => sub { $_[0]->{deleted}; },
            set_specs_for => sub {
                $_[0]->{specs};
            }
        )->to_app;
    };

CONSTRUCTOR ARGUMENTS

store

Type: string

Description: Name of Catmandu store in your catmandu store configuration

Default: default

bag

Type: string

Description: Name of Catmandu bag in your catmandu store configuration

Default: data

This must be a bag that implements Catmandu::CQLSearchable, and that configures a cql_mapping

fix

Either name of fix, path to fix file or instance of Catmandu::Fix

This fix will be applied to every record found, either via GetRecord or ListRecords

deleted

Type: code reference

Description: code reference that is supplied a record, and must return 0 or 1 determing if that record is deleted or not.

Required: false

set_specs_for

Type: code reference

Description: code reference that is supplied a record, and must return an array reference of strings, showing to which sets that record belongs

Required: false

datestamp_field

Type: string

Description: name of the field in the record that contains the oai record datestamp ('datestamp' in our example above)

Required: true

datestamp_index

Type: string

Description: Which CQL index should be used to find records within a specified date range. If not specified, the value from the 'datestamp_field' setting is used

Required: false

repositoryName

Type: string

Description: name of the repository

Required: true

adminEmail

Type: array reference of non empty strings

Description: array reference of administrative emails. These will be included in the Identify response.

Required: false

compression

Type: array reference of non empty strings

Description: a list compression encodings supported by the repository. These will be included in the Identify response.

Required: false

description

Type: array reference of non empty strings

Description: a list of XML containers that describe your repository. These will be included in the Identify response. Note that this module will try to validate the XML data.

Required: false

earliestDatestamp

Type: string

Description: The earliest datestamp available in the dataset formatted as YYYY-MM-DDTHH:MM:SSZ. This will be determined dynamically if no static value is given.

Required: false

deletedRecord

Type: enumeration, having possible values no (default), persistent or transient

Description: The policy for deleted records. See also: https://www.openarchives.org/OAI/openarchivesprotocol.html#DeletedRecords

Required: 1

repositoryIdentifier

Type: string

Description: A prefix to use in OAI-PMH identifiers

Required: true

cql_filter

A global CQL query that is applied to all search requests (GetRecord, ListRecords and ListIdentifiers). Use this to determine what records from your underlying catmandu search store should be available to to the OAI.

default_search_params

Extra search parameters added during search in your catmandu bag:

    $bag->search(
        %{$self->default_search_params},
        cql_query    => $cql,
        sru_sortkeys => $request->sortKeys,
        limit        => $limit,
        start        => $first - 1,
    );

Must be a hash reference

Note that search parameter cql_query, sru_sortkeys, limit and start are overwritten

search_strategy

Type: enumeration having possible value paginate (default), es.scroll or filter

Description: strategy to implement paging of oai record results (in ListRecords or ListIdentifiers). The default search strategy paginate uses start and limit in the underlying search request, but that may lead to deep paging problems. ElasticSearch for example will refuse to return results after hit 10.000.

* paginate: use catmandu store search parameters start and limit in order to advance to the next page. May result into a deep paging problem, but serves as a convenient default for small repositories.

* es.scroll: use ElasticSearch scroll api (https://www.elastic.co/guide/en/elasticsearch/reference/current/scroll-api.html#scroll-api-request) to split into pages. As expected only useful for elasticsearch. Elasticsearch stores a snapshot of the resultset for a certain amount of time, returns the identifier (scroll_id) for that snapshot, and we use that scroll_id as the cursor to the next page. Requesting the first page however several times may cause a server downtime when the resources are exhausted to store an additional snapshot. This option is ONLY included as a deprecated option, never to be used anymore.

* filter: use prefix filtering to split into pages. Works by sorting by on the primary identifier, and using a prefix query like "_id this_page.last_id"> to fetch the next page. This is the RECOMMENDED approach cf. https://solr.apache.org/guide/6_6/pagination-of-results.html#using-cursors

Required: 1

limit

The number of records to be returned in each OAI list record page

When not provided in the constructor, it is derived from the default limit of your catmandu bag (see Catmandu::Searchable#default_limit)

delimiter

Type: string

Description: delimiter used in prefixing a record identifier with a repositoryIdentifier.

Default: :

Required: false

sampleIdentifier

Type: non empty string

Description: sample identifier.

Required: true

xsl_stylesheet

Type: non empty string

Description: url to XSLT stylesheet. When given a link to this stylesheet in every request of type ListRecords or ListIdentifiers. Only useful in browser context where the browser use the stylesheet for dynamic conversion.

Required: false

metadata_formats

Type: array reference of hash reference

Description: An array of metadataFormats that are supported. Every object needs the following attributes:

* metadataPrefix: a short string for the name of the format * schema: an URL to the XSD schema of this format * metadataNamespace: an XML namespace for this format * template: path to a Template Toolkit file to transform your records into this format * fix: optionally an array of one or more Catmandu::Fix-es or Fix files

Required: true

sets

Type: array reference of hash references

Description: an array of OAI-PMH sets and the CQL query to retrieve records in this set from the Catmandu::Store. Each object must have the following attributes:

* setSpec: a short string for the same of the set * setName: a longer description of the set * setDescription: an optional and repeatable container that may hold community-specific XML-encoded data about the set. Should be string or array of strings. * cql: the CQL command to find records in this set in the Catmandu::Store

Required: false

granularity

Type: non empty string

Description: datestamp granularity. Default: YYYY-MM-DDThh:mm:ssZ. This is validated against the returned record timestamps

Required: false

collectionIcon

Type: hash reference

Description: object containing attributes for collectionIcon as used in the Identify response:

* url (required) * link * title * width * height

Required: false

get_record_cql_pattern

Type: non empty string

Description: CQL query template to use when fetching a single record. Defaults to _id exact "%s". Note that the record identifier key as defined by the catmandu bag is taken into account (which is _id by default)

Required: true

datestamp_pattern

Type: non empty string

Description: datestamp pattern for OAI parameters from and until. Example: %Y-%m-%dT%H:%M:%SZ

Required: true

template_options

An optional hash of configuration options that will be passed to Catmandu::Exporter::Template or Template

As this is meant as a drop in replacement for Dancer::Plugin::Catmandu::OAI all arguments should be the same.

So all arguments can be taken from your previous dancer plugin configuration, if necessary:

    use Dancer;
    use Catmandu;
    use Plack::Builder;
    use Plack::App::Catmandu::OAI;

    my $dancer_app = sub {
        Dancer->dance(Dancer::Request->new(env => $_[0]));
    };

    builder {
        enable 'ReverseProxy';
        enable '+Dancer::Middleware::Rebase', base  => Catmandu->config->{uri_base}, strip => 1;
    
        mount "/oai" => Plack::App::Catmandu::OAI->new(
            %{config->{plugins}->{'Catmandu::OAI'}}
        )->to_app;

        mount "/" => builder {
            # only create session cookies for dancer application
            enable "Session";
            mount '/' => $dancer_app;
        };
    };

METHODS

to_app

returns Plack application that can be mounted. Path rebasements are taken into account

AUTHOR

Nicolas Franck, <nicolas.franck at ugent.be>

IMPORTANT

This module is still a work in progress, and needs further testing before using it in a production system

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.