From 349895a5e7b3a71f868829dddf4f38d149325813 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Fri, 29 Sep 2006 16:57:18 +0000 Subject: [PATCH] New -- nearly complete, but CQL section needs work. --- lib/ZOOM/IRSpy/WebService.pod | 200 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 lib/ZOOM/IRSpy/WebService.pod diff --git a/lib/ZOOM/IRSpy/WebService.pod b/lib/ZOOM/IRSpy/WebService.pod new file mode 100644 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, 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 parameter, support for which is +described below, but also by C< C, C and +C. + +=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 parameter, but +also by C and C. + +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 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 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 + +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, Emike@indexdata.comE + +=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; -- 1.7.10.4