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.

A DAIA server can be implemented the following way:

use DAIA;

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'

: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)

message

Includes the function message (DAIA::Message)

:all

Includes all functions.

serve

Calls the method method serve of DAIA::Response so you can choose between function or method calling syntax:

serve( $response, @additionlArgs );
$response->serve( @additionlArgs );

By default all functions are exported (group :all).

Additional functions

parse_xml( $xml, [ $xmlns ] )

First sketch of an XML parser based on XML::Simple. There is little validation only. Not exported by default, but you can call it as DAIA::parse_xml.

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.