SeeAlso::Server - SeeAlso Linkserver Protocol Server


version 0.71


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]); } );



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.


new ( [ %params ] )

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


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


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


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.


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


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.


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.


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

  name => {
     type => "...",
     docs => "...",        # optional
     method => \&code,     # either
     filter => \&code,     # or

or for known formats

  name => 1

You can use this parameter to provide more formats then 'seealso' and 'opensearchdescription' via unAPI. By setting a name to false, it will not be shown - this way you can disable support of opensearchdescription. Known formats are seealso, n3, rdfjson, csv, and redirect.


Subclass of SeeAlso::Identifier to be use when creating an identifier.


Configuration settings as hash reference or as configuration file that will be read into a hash reference. Afterwarrds the The Server section of the configuration is added to the other parameters (existing parameters are not overridden).

query ( $source [, $identifier | $factory [, $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.

param ( $name )

Return the value of a CGI parameter.

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 based on the description of the passed SeeAlso::Source instance.

baseURL ( )

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


xmlencode ( $string )

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


Jakob Voss


This software is copyright (c) 2013 by Jakob Voss.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.