NAME
DAIA - Document Availability Information API
VERSION
version 0.35
SYNOPSIS
This package includes and installs the client program daia
to fetch, validate and convert DAIA data (both command line and CGI). See also the clients
directory for an XML Schema of DAIA/XML and an XSLT script to transform DAIA/XML to HTML.
A DAIA client
use DAIA; # or: use DAIA qw(parse);
$daia = DAIA::parse( $url );
$daia = DAIA::parse( file => $file );
$daia = DAIA::parse( data => $string ); # $string must be Unicode
A DAIA server
use DAIA;
use CGI;
my $id = CGI->new->param('id');
my $r = response( institution => {
href => "http://example.com/your-institution's-homepage",
content => "Your institution's name"
} );
$r->addMessage("en" => "Not an URI: $id", errno => 1 )
unless DAIA::is_uri($id);
my @holdings = get_holding_information($id); # your custom method
if ( @holdings ) {
my $doc = document( id => $id, href => "http://example.com/docs/$id" );
foreach my $h ( @holdings ) {
my $item = item();
my %stor = get_holding_storage( $h ); # your custom method
$item->storage( id => $stor{id}, href => $stor{href}, $stor{name} );
$item->label( get_holding_label( $h ) ); # your custom method
$item->href( get_holding_url( $h ) ); # your custom method
# add availability services
my @services;
if ( get_holding_is_here( $h ) ) { # your custom method
push @services, available('presentation'), available('loan');
} elsif( get_holding_is_not_here( $h ) ) { # your custom method
push @services, # expected to be back in 5 days
unavailable( 'presentation', expected => 'P5D' ),
unavailable( 'loan', expected => 'P5D' );
} else {
# more cases (depending on the complexity of you application)
}
$item->add( @services );
}
$r->document( $doc );
} else {
$r->addMessage( "en" => "No holding information found for id $id" );
}
$r->serve( xslt => "http://path.to/daia.xsl" );
To run your script as CGI, you may have to enable CGI with Options +ExecCGI
and AddHandler cgi-script .pl
in your Apache configuration or in .htaccess
. Some more hints are listed below.
DESCRIPTION
The Document Availability Information API (DAIA) defines a model of information about the current availability of documents, for instance in a library. DAIA includes a specification of serializations in JSON, XML, and RDF. More details can be found in the DAIA specification at http://purl.org/NET/DAIA and at the developer repository at http://daia.sourceforge.net/.
This package provides Perl classes and functions to easily create and manage DAIA information in any form. It can be used to quickly implement DAIA servers, clients, and other programs that handle availability information of documents.
The most important concepts of the DAIA model are:
- documents
-
These abstract works or editions are implemented as objects of class DAIA::Document.
- items
-
These particular copies of documents (physical or digital) are implemented as objects of class DAIA::Item.
- services and
availability status
-
A service is something that can be provided with an item. A particular service has a particular availability status, that is implemented as object of class DAIA::Available or DAIA::Unavailable.
- availability status
-
A boolean value and a service that indicates for what an item is available or not available. Implemented as DAIA::Availability with the subclasses DAIA::Available and DAIA::Unavailable.
- responses
-
A response contains information about the availability of documents at a given point in time, optionally at some specific institution. It is implemented as object of class DAIA::Response.
Additional DAIA objects include institutions (DAIA::Institution), departments (DAIA::Department), storages (DAIA::Storage), messages (DAIA::Message), and errors (DAIA::Message). All these objects provide standard methods for creation, modification, and serialization. This package also exports functions as shorthand for object constructors, for instance the following two result in the same:
item( id => $id );
DAIA::Item->new( id => $id );
FUNCTIONS
By default constructor functions are exported for all objects. To disable exporting, include DAIA like this:
use DAIA qw(); # do not export any functions
use DAIA qw(serve); # only export function 'serve'
use DAIA qw(:core); # only export core functions
You can select two groups, both are exported by default:
:core
-
response
,document
,item
,available
,unavailable
,availability
:entities
-
institution
,department
,storage
,limitation
Additional functions are message
and error
as object constructors, and serve
. The other functions below are not exported by default. You can call them as method or as function, for instance:
DAIA->parse_xml( $xml );
DAIA::parse_xml( $xml );
serve( [ [ format => ] $format ] [ %options ] )
Calls the method method serve
of DAIA::Response or another DAIA object to serialize and send a response to STDOUT with appropriate HTTP headers. You can call it this way:
serve( $response, @additionlArgs ); # as function
$response->serve( @additionlArgs ); # as method
parse ( $from [ %parameters ] )
Parse DAIA/XML or DAIA/JSON from a file or string. You can specify the source as filename, string, or IO::Handle object as first parameter or with the named from
parameter. Alternatively you can either pass a filename or URL with parameter file
or a string with parameter data
. If from
or file
is an URL, its content will be fetched via HTTP. The format
parameter (json
or xml
) is required unless the format can be detected automatically the following way:
A scalar starting with
<
and ending with>
is parsed as DAIA/XML.A scalar starting with
{
and ending with}
is parsed as DAIA/JSON.A scalar ending with
.xml
is is parsed as DAIA/XML file.A scalar ending with
.json
is parsed as DAIA/JSON file.A scalar starting with
http://
orhttps://
is used to fetch data via HTTP. The resulting data is interpreted again as DAIA/XML or DAIA/JSON.
Normally this function or method returns a single DAIA object. When parsing DAIA/XML it may also return a list of objects. It is recommended to always expect a list unless you are absolutely sure that the result of parsing will be a single DAIA object.
parse_xml( $xml )
Parse DAIA/XML from a file or string. The first parameter must be a filename, a string of XML, or a IO::Handle object.
Parsing is more lax then the specification so it silently ignores elements and attributes in foreign namespaces. Returns either a DAIA object or croaks on uncoverable errors.
parse_json( $json )
Parse DAIA/JSON from a file or string. The first parameter must be a filename, a string of XML, or a IO::Handle object.
guess ( $string )
Guess serialization format (DAIA/JSON or DAIA/XML) and return json
, xml
or the empty string.
is_uri ( $value )
Checks whether the value is a well-formed URI. This function is imported from Data::Validate::URI into the namespace of this package as DAIA::is_uri
. On request the function can be exported into the default namespace.
DAIA OBJECTS
All objects (documents, items, availability status, institutions, departments, limitations, storages, messages, errors) are implemented as subclass of DAIA::Object, which is just another Perl meta-class framework. All objects have the following methods:
item
Constructs a new object.
add
Adds typed properties.
xml, struct, json, rdfhash
Returns several serialization forms.
serve ( [ [ format => ] $format | [ cgi => $CGI ] ] [ %more_options ] )
Serialize the object and send it to STDOUT (or to another stream) with the appropriate HTTP headers. This method is available for all DAIA objects but mostly used to serve a DAIA::Response. The serialized object must already be encoded in UTF-8 (but it can contain Unicode strings).
The serialization format can be specified with the first parameter as format
string (json
or xml
) or cgi
object. If no format is given, it is searched for in the CGI query parameters. The default format is xml
. Other possible options are:
- header
-
Print HTTP headers (default). Use
header => 0
to disable headers.Print the XML header of XML format is used. Enabled by default.
- xslt
-
Add a link to the given XSLT stylesheet if XML format is used.
- pi
-
Add one or more processing instructions if XML format is used.
- callback
-
Add this JavaScript callback function in JSON format. If no callback function is specified, it is searched for in the CGI query parameters. You can disable callback support by setting
callback => undef
. - to
-
Serialize to a given stream (IO::Handle, GLOB, or string reference) instead of STDOUT. You may also want to set
exitif
if you use this option. - exitif
-
By setting this method to a true value you make it to exit the program. you provide a method, the method is called and the script exits if only if the return value is true.
DAIA Server hints
DAIA server scripts can be tested on command line by providing HTTP parameters as key=value
pairs.
It is recommended to run a DAIA server via mod_perl or FastCGI so it does not need to be compiled each time it is run. For mod_perl you simply put your script in a directory which PerlResponseHandler
has been set for (for instance to Apache::Registry or ModPerl::PerlRun).
For FastCGI you need to install FCGI and set the CGI handler to "AddHandler fcgid-script .pl" in .htaccess
. Your DAIA server must consist of an initialization section and a response loop:
#!/usr/bin/perl
use DAIA;
use CGI::Fast;
# ...initialization section, which is executed only once ...
while (my $q = new CGI::Fast) { # response loop
my $id = $q->param('id');
# ... create response ...
$response->serve( cgi => $q, exitif => 0 );
}
The serve
methods needs a cgi
or format
parameter and it is been told not to exit the script. It is recommended to check every given timespan whether the script has been modified and restart in this case:
#!/usr/bin/perl
use DAIA;
use CGI::Fast;
my $started = time;
my $thisscript = $0;
my $lastmod = (stat($thisscript))[9] # mtime;
sub restart {
return 0 if time - $started < 10; # check every 10 seconds
return 1 if (stat($thisscript))[9] > $lastmod;
}
while (my $q = new CGI::Fast) { # response loop
# ... create response ...
$response->serve( $q, exitif => \&restart } );
}
AUTHOR
Jakob Voss
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Jakob Voss.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 551:
Unknown directive: =head