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 - please read it to get to know the meaning of the DAIA information objects which are directly mapped to Perl packages.

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.

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:

:core

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

:entities

institution (DAIA::Institution), department (DAIA::department), storage (DAIA::Storage), limitation (DAIA::Limitation)

message

message (DAIA::Message)

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

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.