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.

