NAME

NAME

Dancer::Plugin::Catmandu::SRU - SRU server backed by a searchable
Catmandu::Store

SYNOPSIS

#!/usr/bin/env perl

use Dancer;
use Catmandu;
use Dancer::Plugin::Catmandu::SRU;

Catmandu->load;
Catmandu->config;

my $options = {};

sru_provider '/sru', %$options;

dance;

DESCRIPTION

Dancer::Plugin::Catmandu::SRU is a Dancer plugin to provide SRU
services for Catmandu::Store-s that support CQL (such as
Catmandu::Store::ElasticSearch). Follow the installation steps below to
setup your own SRU server.

REQUIREMENTS

In the examples below an ElasticSearch 1.7.2
https://www.elastic.co/downloads/past-releases/elasticsearch-1-7-2
server will be used:

$ cpanm Dancer Catmandu::SRU Catmandu::Store::ElasticSearch

$ wget https://download.elastic.co/elasticsearch/elasticsearch/elasticsearch-1.7.2.zip
$ unzip elasticsearch-1.7.2.zip
$ cd elasticsearch-1.7.2
$ bin/elasticsearch

RECORDS

Records stored in the Catmandu::Store can be in any format. Preferably
the format should be easy to convert into an XML format. At a minimum
each record contains an identifier '_id'. In the examples below we'll
configure the SRU to serve Dublin Core records:

$ cat sample.yml
---
_id: 1
creator:
- Musterman, Max
- Jansen, Jan
- Svenson, Sven
title:
- Test record
...

CATMANDU CONFIGURATION

ElasticSearch requires a configuration file to map record fields to CQL
terms. Below is a minimal configuration required to query for '_id' and
'title' and 'creator' in the ElasticSearch collection:

$ cat catmandu.yml
---
store:
sru:
package: ElasticSearch
options:
index_name: sru
bags:
data:
cql_mapping:
default_index: basic
indexes:
_id:
op:
'any': true
'all': true
'=': true
'exact': true
field: '_id'
creator:
op:
'any': true
'all': true
'=': true
'exact': true
field: 'creator'
title:
op:
'any': true
'all': true
'=': true
'exact': true
field: 'title'

IMPORT RECORDS

With the Catmandu configuration files in place records can be imported
with the catmandu command:

# Drop the existing ElasticSearch 'sru' collection
$ catmandu drop sru

# Import the sample record
$ catmandu import YAML to sru < sample.yml

# Test if the records are available in the 'sru' collection
$ catmandu export sru

DANCER CONFIGURATION

The Dancer configuration file 'config.yml' contains basic information
for the OAI-PMH plugin to work:

* store - In which Catmandu::Store are the metadata records stored
* bag - In which Catmandu::Bag are the records of this 'store' (use: 'data' as default)
* cql_filter - A CQL query to find all records in the database that should be made available to SRU
* default_record_schema - The metadataSchema to present records in
* limit - The maximum number of records to be returned in each SRU request
* maximum_limit - The maximum number of search results to return
* record_schemas - An array of all supported record schemas
* identifier - The SRU identifier for the schema (see L<http://www.loc.gov/standards/sru/recordSchemas/>)
* name - A short descriptive name for the schema
* fix - Optionally an array of fixes to apply to the records before they are transformed into XML
* template - The path to a Template Toolkit file to transform your records into this format
* template_options - An optional hash of configuration options that will be passed to L<Catmandu::Exporter::Template> or L<Template>.

Below is a sample minimal configuration for the 'sample.yml' demo
above:

charset: "UTF-8"
plugins:
'Catmandu::SRU':
store: sru
bag: data
default_record_schema: dc
limit: 200
maximum_limit: 500
record_schemas:
-
identifier: "info:srw/schema/1/dc-v1.1"
name: dc
template: dc.tt

METADATA FORMAT TEMPLATE

For each metadata format a Template Toolkit file needs to exist which
translate Catmandu::Store records into XML records. The example below
contains an example file to transform 'sample.yml' type records into
SRU DC:

$ cat dc.tt
<srw_dc:dc xmlns:srw_dc="info:srw/schema/1/dc-schema"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="info:srw/schema/1/dc-schema http://www.loc.gov/standards/sru/recordSchemas/dc-schema.xsd">
[%- FOREACH var IN ['title' 'creator' 'subject' 'description' 'publisher' 'contributor' 'date' 'type' 'format' 'identifier' 'source' 'language' 'relation' 'coverage' 'rights'] %]
[%- FOREACH val IN $var %]
<dc:[% var %]>[% val | html %]</dc:[% var %]>
[%- END %]
[%- END %]
</srw_dc:dc>

START DANCER

If all the required files are available, then a Dancer application can
be started. See the 'demo' directory of this distribution for a
complete example:

$ ls
app.pl catmandu.yml config.yml dc.tt
$ cat app.pl
#!/usr/bin/env perl

use Dancer;
use Catmandu;
use Dancer::Plugin::Catmandu::SRU;

Catmandu->load;
Catmandu->config;

my $options = {};

sru_provider '/sru', %$options;

dance;

# Start Dancer
$ perl ./app.pl

# Test queries:
$ curl "http://localhost:3000/sru"
$ curl "http://localhost:3000/sru?version=1.1&operation=searchRetrieve&query=(_id+%3d+1)"
$ catmandu convert SRU --base 'http://localhost:3000/sru' --query '(_id = 1)'

AUTHOR

Nicolas Steenlant, <nicolas.steenlant at ugent.be>

CONTRIBUTOR

Vitali Peil, <vitali.peil at uni-bielefeld.de>

Patrick Hochstenbach, <patrick.hochstenbach at ugent.be>

SEE ALSO

SRU, Catmandu, Catmandu::Store::ElasticSearch , Catmandu::SRU

LICENSE

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.