NAME

Plack::App::RDF::Files - Serve RDF data from files

VERSION

version 0.02

SYNOPSIS

my $app = Plack::App::RDF::Files->new(
    base_dir => '/var/rdf/
);

# Requests URI            =>  RDF files
# http://example.org/     =>  /path/to/rdf/*.(nt|ttl|rdfxml)
# http://example.org/foo  =>  /path/to/rdf/foo/*.(nt|ttl|rdfxml)
# http://example.org/x/y  =>  /path/to/rdf/x/y/*.(nt|ttl|rdfxml)

DESCRIPTION

This PSGI application serves RDF from files. Each accessible RDF resource corresponds to a (sub)directory, located in a common based directory. All RDF files in a directory are merged and returned as RDF graph.

METHODS

files( $env | $req | $str )

Get a list of RDF files that will be read for a given request. The request can be specified as PSGI environment, as Plack::Request, or as partial URI that follows base_uri (given as string). The requested URI is saved in field rdf.uri of the request environment. On success returns the base directory and a list of files, each mapped to its last modification time. Undef is returned if the request contained invalid characters (everything but a-zA-Z0-9:.@- and the forbidden sequence ../) or if the request equals ro the base URI and include_index was not enabled.

negotiate( $env )

This internal methods selects an RDF serializer based on the PSGI environment variable negotiate.format (see Plack::Middleware::Negotiate) or the negotiate method of RDF::Trine::Serializer. Returns first a RDF::Trine::Serializer on success or undef on error) and second a (possibly empty) list of HTTP response headers.

CONFIGURATION

base_dir

Mandatory base directory that all resource directories are located in.

base_uri

The base URI of all resources. If no base URI has been specified, the base URI is taken from the PSGI request.

file_types

An array of RDF file types (extensions) to look for. Set to ['rdfxml','nt','ttl'] by default.

include_index

By default a HTTP 404 error is returned if one tries to access the base directory. Enable this option to also serve RDF data from this location.

index_property

RDF property to use for listing all resources connected to the base URI (if <include_index> is enabled). Set to rdfs:seeAlso by default. Can be disabled by setting a false value.

path_map

Optional code reference that maps a local part of an URI to a relative directory. Set to the identity mapping by default.

namespaces

Optional namespaces for serialization, passed to RDF::Trine::Serializer.

PSGI environment variables

The following PSGI environment variables are relevant:

rdf.uri

The requested URI

rdf.iterator

The RDF::Trine::Iterator that will be used for serializing, if psgi.streaming is set. One can use this variable to catch the RDF data in another post-processing middleware.

rdf.files

An hash of source filenames, each with the number of triples (on success) as property size, an error message as error if parsing failed, and the timestamp of last modification as mtime. size and error may not be given before parsing, if rdf.iterator is set.

LIMITATIONS

This module is an early developer release. Be warned!

All resource URIs to be served must have a common URI prefix (such as http://example.org/ above) and a local part that may be restricted to a limited set of characters. For instance the character sequence ../ is not allowed.

NOTES

If an existing resource does not contain triples, the axiomatic triple ?uri rdf:type rdfs:Resource is returned.

To update the files, add a middleware that catches 404 and 202 responses.

TODO

VoID descriptions could be added, possibly with RDF::Generator::Void.

SEE ALSO

Use Plack::Middleware::Negotiate to add content negotiation based on an URL parameter and/or suffix.

See RDF::LinkedData for a different module to serve RDF as linked data. See also RDF::Flow and RDF::Lazy for processing RDF data.

See http://foafpress.org/ for a similar approach in PHP.

AUTHOR

Jakob Voß <voss@gbv.de>

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.

cpanm Plack::App::RDF::Files

perl -MCPAN -e shell
install Plack::App::RDF::Files