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

To implement a SeeAlso linkserver, you need instances of SeeAlso::Server, and SeeAlso::Source. The Source object must return a SeeAlso::Response object:

  use SeeAlso::Server;
  my $server = SeeAlso::Server->new( cgi => $cgi );

  use SeeAlso::Source;
  use SeeAlso::Response;
  my $source = SeeAlso::Source->new( sub {
      my $identifier = shift;
      return unless $identifier->valid;

      my $response = SeeAlso::Response->new( $identifier );

      # add response content depending on $identifier->value
      $response->add( $label, $description, $uri );
      # ...

      return $response;
  } );
  $source->description( "ShortName" => "MySimpleServer" );

  my $http = $server->query( $source );
  print $http;

Or even smaller with the exported function query_seealso_server:

  use SeeAlso::Server;
  print query_seealso_server(
      sub {
          my $identifier = shift; 
          ....
          return $response; 
      },
      [ "ShortName" => "MySimpleServer" ]
  );

The examples directory contains a full example. For more specialised servers you may also need to use SeeAlso::Identifier or one of its subclasses and another subclass of SeeAlso::Source.

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. An XSLT to display a full demo client is available.

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

a string (or function) that contains (or returns) an OpenSearch Description document as XML string. By default the openSearchDescription method of this class is used. You can switch off support of OpenSearch Description by setting opensearchdescription to the empty string.

debug

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

logger ( [ $logger ] )

Get/set a logger for this server. The logger must be of class SeeAlso::Logger.

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

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

openSearchDescription ( [$source] )

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

baseURL

Return the full SeeAlso base URL of this server. Append the <tt>format=seealso</tt> parameter to get a SeeAlso simple base URL.

ADDITIONAL FUNCTIONS

query_seealso_server ( $source [, \@description ] [, %params ] )

This function is a shortcut method to create and query a SeeAlso server in one command. It is exported by default. The following line is a identifcal to the second:

  query_seealso_server( $source, %params );

  SeeAlso::Server->new( %params )->query( $source, $params{id} );

If $params{id} is not set, the id parameter of the CGI object ($param{cgi} or CGI-new>) is used.

If you pass an array reference as $source instead of a SeeAlso::Source object, a new SeeAlso::Source will be generated with @{$source} as parameters. The following line is a identifcal to three next commands:

  query_seealso_server( \&query_function, \@description, %params );

  $source = SeeAlso::Source->new( \&query_function, @description );
  $server = SeeAlso::Server->new( %params );
  $server->query( $source, $params{id} );

Please note that you must pass the optional @description parameter as an array reference. Here is an example:

  query_seealso_server( 
     sub { ... }, 
     [ "ShortName" => "..." ],
     logger => SeeAlso::Logger->new(...)
  );

xmlencode ( $string )

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

cpanm SeeAlso::Server

perl -MCPAN -e shell
install SeeAlso::Server