Jakob Voß > Plack-App-DAIA-0.53 > Plack::App::DAIA

Download:
Plack-App-DAIA-0.53.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.53   Source   Latest Release: Plack-App-DAIA-0.55

NAME ^

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

VERSION ^

version 0.53

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 (disabled by default). Any numeric value will be set to daia.xsl, so use xslt => 1 for enabling the default XSLT client. 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.

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

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) 2013 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.

syntax highlighting: