NAME

SeeAlso::Server - SeeAlso-API Webservice Implementation

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 implements the unAPI protocol version 1.

SYNOPSIS

You need instances of SeeAlso::Source and SeeAlso::Identifier for usage of a SeeAlso Server.

use SeeAlso::Server;

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

# ... set $identifier based on $cgi->param('id') and:
my $http = $server->query( $source, $identifier );

# ... or also set $format and $callback and:
my $http = $server->query( $source, $identifier, $format, $callback );

print $http;

To create a special server, you probably have to create subclasses of SeeAlso::Source and SeeAlso::Identifier.

EXAMPLE

The following script implements a minimal SeeAlso service:

use SeeAlso::Server;
use SeeAlso::Source;

sub query_method {
    my $identifier = shift;
    my $response = SeeAlso::Response->new($identifier);

    # depending on $identifier->value do zero or more:
    $response->add("..title..","..description..","..url..");

    return $response;
}

my $server = SeeAlso::Server->new();
my @about = ( "ShortName" => "My simple SeeAlso service" );
my $source = SeeAlso::Source->new( \&query_method, @about );

print $server->query( $source );

The Service will also fullfill the SeeAlso specification if the query method breaks or does not return a SeeAlso::Response object.

METHODS

new ( [%params] )

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

cgi

a CGI object to print HTTP headers. If not specified, a new CGI object is created.

description

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

listFormats ( $response [, @formats] )

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

The optional second parameter may contain an array of additional formats, each beeing a hash with 'name', 'type' and optional 'docs' field as defined in the unAPI standard version 1.

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.

If you do not provide one or more of the parameters $identifer, $format, and $callback, it is tried to get the parameters 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.

ADDITIONAL FUNCTIONS

xmlencode ( $string )

Replace &, <, >, " by XML entities