/ 
SeeAlso-Server-0.48
River stage one • 2 direct dependents • 2 total dependents
/ SeeAlso::Server

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;

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

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.

logger

a <SeeAlso::Logger> object for logging.

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.

logger ( [ $logger ] )

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

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. You can use this parameter to provide more formats then 'seealso' and 'opensearchdescription' via unAPI.

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.

ADDITIONAL FUNCTIONS

xmlencode ( $string )

Replace &, <, >, " by XML entities