New -- nearly complete, but CQL section needs work.

diff --git a/lib/ZOOM/IRSpy/WebService.pod b/lib/ZOOM/IRSpy/WebService.pod
new file mode 100644 (file)
index 0000000..a66ee6c
--- /dev/null
+++ b/lib/ZOOM/IRSpy/WebService.pod
@@ -0,0 +1,200 @@
+# $Id: WebService.pod,v 1.1 2006-09-29 16:57:18 mike Exp $
+
+package ZOOM::IRSpy::WebService;
+
+=head1 NAME
+
+ZOOM::IRSpy::WebService - Accessing the IRSpy database as a Web Service
+
+=head1 INTRODUCTION
+
+Because IRSpy keeps its information about targets as ZeeRex records in
+a Zebra database, that information is available via the SRU and SRW
+web services.  These two services are very closely related: the former
+REST-like, based on HTTP GET URLs, and the latter SOAP-based.  Both
+use the same query language (CQL) and the same XML-based result
+formats.
+
+(In addition, Zebra provides ANSI/NISO Z39.50 services, but these are
+not further discussed here.)
+
+=head1 EXAMPLE
+
+Here is a example SRU URL that accesses the IRSpy database of the live
+system (although it will not be accessible to most clients due to
+firewall issues.  It is broken across lines for clarity:
+
+       http://irspy.indexdata.com:3313/IR-Explain---1?
+               version=1.1&
+               operation=searchRetrieve&
+               query=net.port=3950&
+               maximumRecords=10&
+               recordSchema=zeerex
+=cut
+
+# http://irspy.indexdata.com:3313/IR-Explain---1?version=1.1&operation=searchRetrieve&query=net.port=3950&maximumRecords=10&recordSchema=zeerex
+
+=pod
+
+It is beyond the scope of this document to provide a full SRU
+tutorial, but briefly, the URL above consists of the following parts:
+
+=over 4
+
+=item http://irspy.indexdata.com:3313
+
+The base-URL of the SRU server.
+
+=item IR-Explain---1
+
+The name of the SRU database.
+
+=item version=1.1, operation=searchRetrieve, etc.
+
+SRU parameters specifying the operation requested.
+
+=back
+
+The parameters are as follows:
+
+=over 4
+
+=item version=1.1
+
+Mandatory - SRU requests must contain an explicit version identifier,
+and Zebra supports only version 1.1.
+
+=item operation=searchRetrieve
+
+Mandatory - SRU requests must contain an operation.  Zebra supports
+several, as discussed below.
+
+=item query=net.port=3950
+
+When the operation is C<searchRetrieve>, a query must be specified.
+The query is always expressed in CQL (Common Query Language), which
+Zebra's IRSpy database supports as described below.
+
+=item maximumRecords=10
+
+Optional.  Specifies how many records to include in a search
+response.  When omitted, defaults to zero: the response includes a
+hit-count but no records.
+
+=item recordSchema=zeerex
+
+Optional.  Specifies what format the included XML records, if any,
+should be in.  If omitted, defaults to "dc" (Dublin Core).  Zebra's
+IRSpy database supports several schemas as described below.
+
+=back
+
+=head1 SUPPORT
+
+=head2 SUPPORTED OPERATIONS
+
+Zebra supports the following SRU operations:
+
+=over 4
+
+=item explain
+
+This operation requires no further parameters, and returns a ZeeRex
+record describing the IRSpy database itself.
+
+=item searchRetrieve
+
+This is the principle operation of SRU, combining searching of the
+database and retrieval of the records that are found.  Its behaviour
+is specified primarily by the C<query> parameter, support for which is
+described below, but also by C< C<startRecord>, C<maximumRecords> and
+C<recordSchema>.
+
+=item scan
+
+This operation scans an index of the database and returns a list of
+candidate search terms for that index, including hit-counts.  Its
+behaviour is specified primarily by the C<scanClause> parameter, but
+also by C<maximumTerms> and C<responsePosition>.
+
+Here is an example SRU Scan URL:
+
+       http://irspy.indexdata.com:3313/IR-Explain---1?
+               version=1.1&
+               operation=scan&
+               scanClause=dc.title=fish
+
+This lists all words occurring in titles, in alphabetical order,
+beginning with "fish" or, if that word does not occur in any title,
+the word that immediately follows it alphabetically.
+
+The C<scanClause> parameter is a tiny query, consisting only an
+index-name, a relation (usually "=") and a term.  The supported index
+names are the same as those listed below.
+
+=back
+
+=head2 CQL SUPPORT
+
+I<###>
+
+=head2 RECORD SCHEMAS
+
+The IRSpy Zebra database supports record retrieval using the following
+schemas:
+
+=over4
+
+=item dc
+
+Dublin Core records (title, creator, description, etc.)
+
+=item zeerex
+
+ZeeRex records, the definitive version of the information that drives
+the database.  These records use an extended version of the ZeeRex 2.0
+schema that also includes an <irspy:status> element at the end of the
+record.
+
+=item index
+
+An XML format that prescribes how the record is indexed for
+searching.  This is useful for debugging, but not likely to be very
+exciting for casual passers-by.
+
+=back
+
+=head1 SEE ALSO
+
+C<ZOOM::IRSpy>
+
+The specifications for SRU (REST-like Web Service) at
+http://www.loc.gov/sru
+
+The specifications for SRW (SOAP-based Web Service) at
+http://www.loc.gov/srw
+
+The Z39.50 specifications at
+http://lcweb.loc.gov/z3950/agency/
+
+The ZeeRex specifications at
+http://explain.z3950.org/
+
+The Zebra database at
+http://indexdata.com/zebra
+
+=head1 AUTHOR
+
+Mike Taylor, E<lt>mike@indexdata.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2006 by Index Data ApS.
+
+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.7 or,
+at your option, any later version of Perl 5 you may have available.
+
+=cut
+
+1;