/ 
DAIA-0.25
River stage one • 1 direct dependent • 1 total dependent
/ DAIA

NAME

DAIA - Document Availability Information API in Perl

DESCRIPTION

The Document Availability Information API (DAIA) defines a data model with serializations in JSON and XML to encode information about the current availability of documents. See http://purl.org/NET/DAIA for a detailed specification. This package provides Perl classes and functions to easily create and manage DAIA information. It can be used to implement DAIA servers, clients, and other programs that handle availability information.

The DAIA information objects as decriped in the DAIA specification are directly mapped to Perl packages. In addition a couple of functions can be exported if you prefer to handle DAIA data without much object-orientation.

SYNOPSIS

A DAIA client (with some variations):

use DAIA;
use utf8;

# get via URL and parse  
use LWP::Simple;
$daia = DAIA::parse( data => get( $url ) );

# read a file and parse
$daia = DAIA::parse( file => $file );

# parse a string
use Encode; # if incoming data is unencoded UTF-8
$data = Encode::decode_utf8( $data ); # skip this if $data is just Unicode

$daia = DAIA::parse( data => $string );

A DAIA server:

use DAIA;
use utf8;

my $res = response(
    institution => {
      href    => "http://example.com/homepage.of.institutiong",
      content => "Name of the Institution" 
    }
);

my $id = '12345'; # identifier that has been queried for

my @holdings = get_holding_information($id);  # you need to implement this!

if ( @holdings ) {
  my $doc = document( id => $id, href => "http://example.com/docs/$id" );
  foreach my $h ( @holdings ) {
    my $item = item();

    # add some general information if you implement get_holding_... functions

    my %sto = get_holding_storage( $h );  
    $item->storage( id => $sto{id}, href => $sto{href}, $sto{name} );

    my $label = get_holding_label( $h );
    $item->label( $label );

    my $url = get_holding_url( $h );
    $item->href( $url );

    # add availability services
    my @services;

    if ( get_holding_is_here( $h ) ) {
       push @services, available('presentation'), available('loan');
    } elsif( get_holding_is_not_here( $h ) ) {
      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 );
  }
  $res->document( $doc );
} else {
   $res->message( "en" => "No holding information found for id $id" );
}

$res->serve( xslt => "http://path.to/daia.xsl" );

EXPORTED FUNCTIONS

If you prefer function calls in favor of constructor calls, this package providesfunctions for each DAIA class constructor. The functions are named by the object that they create but in lowercase - for instance response for the DAIA::Response object. The functions can be exported in groups. To disable exporting of the functions include DAIA like this:

use DAIA qw();      # do not export any functions
use DAIA qw(serve); # only export function 'serve'

By default all functions are exported (group :all) in addition you can specify the following groups:

:core

Includes the functions response (DAIA::Response), document (DAIA::Document), item (DAIA::Item), available (DAIA::Available), unavailable (DAIA::Unavailable), and availability (DAIA::Availability)

:entities

Includes the functions institution (DAIA::Institution), department (DAIA::department), storage (DAIA::Storage), and limitation (DAIA::Limitation)

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

ADDITIONAL FUNCTIONS

The following functions are not exportted but you can call both them as function and as method:

DAIA->parse_xml( $xml );
DAIA::parse_xml( $xml );

parse_xml( $xml, [ xmlns => 0|1 ] )

Parse DAIA/XML from a file or string. The first parameter must be a filename, a string of XML, or a IO::Handle object. The optional parameter xmlns defines whether parsing is namespace-aware - in this case all elements outside the DAIA XML namespace http://ws.gbv.de/daia/ are ignored.

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.

parse ( $from [ %parameter ] )

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 pass a file(name) with parameter file or a string with parameter data which is more secure. 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 DAIA/XML.

  • A scalar starting with { and ending with } is DAIA/JSON.

  • A scalar ending with .json is a DAIA/JSON.

  • A scalar ending with .xml is a DAIA/XML.

If you specify a filename with parameter file it will not tried to parse the filename as DAIA content but only as filename.

guess ( $string )

Guess serialization format (DAIA/JSON or DAIA/XML) and return json, xml or the empty string.

AUTHOR

Jakob Voss <jakob.voss@gbv.de>

LICENSE

Copyright (C) 2009 by Verbundzentrale Goettingen (VZG) and Jakob Voss

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.