NAME

SeeAlso::Server - SeeAlso Linkserver Protocol Server

DESCRIPTION

Basic module for a Webservice that implements the SeeAlso link server Protocol. SeeAlso is a combination of unAPI and OpenSearch Suggestions, so this module also implements the unAPI protocol version 1.

SYNOPSIS

The core of every SeeAlso linkserver is a query method that gets a SeeAlso::Identifier and returns a SeeAlso::Response.

  use SeeAlso::Server;
  use SeeAlso::Response;

  sub query {
      my $identifier = shift;

      my $response = SeeAlso::Response->new( $identifier );
      $response->add( $label, $description, $uri );

      return $response;
  }

  my @description = ( "ShortName" => "MySimpleServer" );
  my $server = SeeAlso::Server->new( description => \@description );
  my $http = $server->query( \&query );
  print $http;

Instead of providing a simple query method, you can also use a SeeAlso::Source object. Identifiers can be validated and normalized with a validation method or a SeeAlso::Identifier object.

  # get responses from a database (not implemented yet)
  my $source = SeeAlso::Source::DBI->new( $connection, $sqltemplate );

  # automatically convert identifier to uppercase
  print $server->query( $source, sub { return uc($_[0]); } );

METHODS

new ( [ %params ] )

Creates a new SeeAlso::Server object. You may specify the following parameters:

cgi

a CGI object. If not specified, a new CGI object is created.

xslt

the URL (relative or absolute) of an XSLT script to display the unAPI format list. It is recommended to use the XSLT client 'showservice.xsl' that is available in the 'client' directory of this package.

clientbase

the base URL (relative or absolute) of a directory that contains client software to access the service. Only needed for the XSLT script so far.

description

By default the openSearchDescription method is used to create the self-description of a server based on a SeeAlso::Source. You can disable support of OpenSearch Description by setting this parameter to false or override the description by setting this parameter to an array reference.

expires

Send HTTP "Expires" header for caching (see the setExpires method for details).

debug

Debug level. By default (0) format=debug adds debugging information as JavaScript comment in the JSON response. You can force this with debug = 1 and prohibit with debug = -1.

logger

set a SeeAlso::Logger for this server. See the method logger below.

formats

An additional hash of formats (experimental). The structure is:

  name => {
     type => "...",
     docs => "...",         # optional
     method => \&function
 }

You can use this parameter to provide more formats then 'seealso' and 'opensearchdescription' via unAPI (these two formats cannot be overwritten).

query ( $source [, $identifier [, $format [, $callback ] ] ] )

Perform a query by a given source, identifier, format and (optional) callback parameter. Returns a full HTTP message with HTTP headers. Missing parameters are tried to get from the server's CGI object.

This is what the method actually does: The source (of type SeeAlso::Source) is queried for the identifier (of type SeeAlso::Identifier or a plain string or function). Depending on the response (of type SeeAlso::Response) and the requested format ('seealso' or 'opensearchdescription' for valid responses) the right HTTP response is returned. This can be either a list of formats in unAPI Response format (XML), or a list of links in OpenSearch Suggestions Response format (JSON), or an OpenSearch Description Document (XML).

This method catches all warnings and errors that may occur in the query method and appends them to the error list that can be accessed by the errors method. The error list is cleaned before each call of query.

logger ( [ $logger ] )

Get/set a logger for this server. The logger must be of class SeeAlso::Logger or it will be passed to its constructor. This means you can also use references to file handles and IO::Handle objects.

setExpires( $expires )

Set "Expires" HTTP header for cache control. The parameter is expected to be either a HTTP Date (better use HTTP::Date to create it) or a string such as "now" (immediately), "+180s" (in 180 seconds), "+2m" (in 2 minutes), "+12h" (in 12 hours), "+1d" (in 1 day), "+3M" (in 3 months), "+1y" (in 1 year), "-3m" (3 minutes ago).

The "Expires" header is only sent for responses in seealso format!

listFormats ( $response )

Return a HTTP response that lists available formats according to the unAPI specification version 1. You must provide a SeeAlso::Response object. If this response has no query then no unAPI parameter was provided so HTTP status code 200 is returned. Otherwise the status code depends on whether the response is empty (HTTP code 404) or not (HTTP code 300).

errors ( [ $message ] )

Returns a list of errors and warning messages that have ocurred during the last query. You can also add an error message but this is only useful interally.

openSearchDescription ( [ $source ] )

Returns an OpenSearch Description document. If you pass a SeeAlso::Source instance, additional information will be added.

baseURL ( )

Return the full SeeAlso base URL of this server. You can append the 'format=seealso' parameter to get a SeeAlso simple base URL.

ADDITIONAL FUNCTIONS

xmlencode ( $string )

Replace &, <, >, " by XML entities.

AUTHOR

Jakob Voss <jakob.voss@gbv.de>

LICENSE

Copyright (C) 2007-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.

cpanm SeeAlso::Server

perl -MCPAN -e shell
install SeeAlso::Server