/ 
Plack-App-DAIA-0.55
River stage zero No dependents
/ Plack::App::DAIA

NAME

Plack::App::DAIA - DAIA Server as Plack application

VERSION

version 0.55

SYNOPSIS

Either derive from Plack::App::DAIA

package Your::App;
use parent 'Plack::App::DAIA';

sub init {
    my $self = shift;
    $self->idformat( qr{^[a-z]+:.*$} ) unless $self->idformat;
}

sub retrieve {
    my ($self, $id, %idparts) = @_;

    my $daia = DAIA::Response->new;

    # construct full response ...

    return $daia;
};

1;

or pass a code reference as option code:

use Plack::App::DAIA;

Plack::App::DAIA->new(
    code => sub {
        my ($id, %idparts) = @_;

        my $daia = DAIA::Response->new;

        # construct full response ...

        return $daia;
    },
    idformat => qr{^[a-z]+:.*$}
);

DESCRIPTION

This module implements a Document Availability Information API (DAIA) server as PSGI application. A DAIA server receives two URL parameters:

id

refers to the document to retrieve availability information. The id is parsed based on the "idformat" option and passed to an internal "retrieve" method, which must return a DAIA::Response object.

format

specifies a DAIA serialization format, that the resulting DAIA::Response is returned in. By default the formats xml (DAIA/XML, the default), json (DAIA/JSON), and rdfjson (DAIA/RDF in RDF/JSON) are supported. Additional RDF serializations (rdfxml, turtle, and ntriples) are supported if RDF::Trine is installed. If RDF::NS is installed, the RDF/Turtle output uses well-known namespace prefixes. Visual RDF graphs are supported with format svg and dot if RDF::Trine::Exporter::GraphViz is installed and dot is in $ENV{PATH}.

This module automatically adds appropriate warnings and error messages. A simple HTML interface based on client side XSLT is added with option xslt.

METHODS

new ( [%options] )

Creates a new DAIA server. Supported options are

code

Code reference to the retrieve method if you prefer not to create a module derived from this module.

xslt

Path of a DAIA XSLT client to attach to DAIA/XML responses. Set to daia.xsl by default. The default client is provided in form of three files (daia.xsl, daia.css, xmlverbatim.xsl) and DAIA icons, all shipped together with this module. Enabling HTML client also enables serving the DAIA XML Schema as daia.xsd.

Set xslt => 0 to disable the client.

You may need to adjust the path if your server rewrites the request path.

root

Path of a directory with XSLT client files.

warnings

Enable warnings in the DAIA response (enabled by default).

errors

Enable warnings and directly return a response without calling the retrieve method on error.

idformat

Optional regular expression to validate identifiers. Invalid identifiers are set to the empty string before they are passed to the retrieve method. In addition an error message "unknown identifier format" is added to the response, if the option warnings are enabled. If the option errors is enabled, the retrieve method is not called on error.

It is recommended to use regular expressions with named capturing groups as introduced in Perl 5.10. The named parts are also passed to the retrieve method. For instance:

idformat => qr{^ (?<prefix>[a-z]+) : (?<local>.+) $}x

will give you $parts{prefix} and $parts{local} in the retrieve method.

safe

Catch errors on the request format if enabled (by default). You may want to disable this to get a stack trace if the request method throws an error.

initialized

Stores whether the application had been initialized.

retrieve ( $id [, %parts ] )

Must return a status and a DAIA::Response object. Override this method if you derive an application from Plack::App::DAIA. By default it either calls the retrieve code, as passed to the constructor, or returns undef, so a HTTP 500 error is returned.

This method is passed the original query identifier and a hash of named capturing groups from your identifier format.

init

This method is called by Plack::Component::prepare_app, once before the first request and before undefined options are set to their default values. You can define this method in you subclass as initialization hook, for instance to set default option values. Initialization during runtime can be triggered by setting initialized to false.

as_psgi ( $status, $daia [, $format [, $callback ] ] )

Serializes a DAIA::Response in some DAIA serialization format (xml by default) and returns a a PSGI response with given HTTP status code.

EXAMPLES

You can also mix this application with Plack middleware.

It is highly recommended to test your services! Testing is made as easy as possible with the provedaia command line script.

This module contains a dummy application app.psgi and a more detailed example examples/daia-ubbielefeld.pl.

SEE ALSO

Plack::App::DAIA is derived from Plack::Component. Use Plack::DAIA::Test and provedaia (using Plack::App::DAIA::Test::Suite) for writing tests. See Plack::App::DAIA::Validator for a DAIA validator and converter.

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Jakob Voß.

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