From: Mike Taylor Date: Wed, 15 Feb 2006 16:54:36 +0000 (+0000) Subject: Invocation explained. X-Git-Tag: before.bug.529~243 X-Git-Url: http://sru.miketaylor.org.uk/cgi-bin?a=commitdiff_plain;h=be1ed58119bbbc6063723f1a255ab67e18885d8f;p=idzebra-moved-to-github.git Invocation explained. --- diff --git a/doc/server.xml b/doc/server.xml index 87137b2..c39b4ab 100644 --- a/doc/server.xml +++ b/doc/server.xml @@ -1,5 +1,5 @@ - + The Z39.50 Server @@ -52,7 +52,7 @@ &zebrasrv-options; - VIRTUAL HOSTS + VIRTUAL HOSTS zebrasrv uses the YAZ server frontend and does support multiple virtual servers behind multiple listening sockets. @@ -558,15 +558,131 @@ The SRU/SRW Server + + In addition to Z39.50, Zebra supports the more recent and + web-friendly IR protocol SRU, described at + . + SRU is ``Search/Retrieve via URL'', a simple, REST-like protocol + that uses HTTP GET to request search responses. The request + itself is made of parameters such as + query, + startRecord, + maximumRecords + and + recordSchema; + the response is an XML document containing hit-count, result-set + records, diagnostics, etc. SRU can be thought of as a re-casting + of Z39.50 semantics in web-friendly terms; or as a standardisation + of the ad-hoc query parameters used by search engines such as Google + and AltaVista; or as a superset of A9's OpenSearch (which it + predates). + + + Zebra further supports SRW, described at + . + SRW is the ``Search/Retrieve Web Service'', a SOAP-based alternative + implementation of the abstract protocol that SRU implements as HTTP + GET requests. In SRW, requests are encoded as XML documents which + are posted to the server. The responses are identical to those + returned by SRU servers, except that they are wrapped in a several + layers of SOAP envelope. + + + Zebra supports all three protocols - Z39.50, SRU and SRW - on the + same port, recognising what protocol is used by each incoming + requests and handling them accordingly. This is a achieved through + the use of Deep Magic; civilians are warned not to stand too close. + Running the SRU/SRW Server (zebrasrv) - Placeholder for DocBook's facist schema + + Because Zebra supports all three protocols on one port, it would + seem to follow that the SRU/SRW server is run in the same way as + the Z39.50 server, as described above. This is true, but only in + an uninterestingly vacuous way: a Zebra server run in this manner + will indeed recognise and accept SRU and SRW requests; but since it + doesn't know how to handle the CQL queries that these protocols + use, all it can do is send failure responses. + + + + It is possible to cheat, by having SRU or SRW search Zebra with + a PQF query instead of CQL, using the + x-pquery + parameter instead of + query. + This is a + non-standard extension + of CQL, and a + very naughty + thing to do, but it does give you a way to see Zebra serving SRU + ``right out of the box''. If you start your favourite Zebra + server in the usual way, on port 9999, then you can send your web + browser to: + + + http://localhost:9999/Default?version=1.1& + operation=searchRetrieve& + x-pquery=mineral& + startRecord=1& + maximumRecords=1 + + + This will display the XML-formatted SRU response that includes the + first record in the result-set found by the query + mineral. (For clarity, the SRU URL is shown + here broken across lines, but the lines should be joined to gether + to make single-line URL for the browser to submit.) + + + + In order to turn on Zebra's support for CQL queries, it's necessary + to have the YAZ generic front-end (which Zebra uses) translate them + into the Z39.50 Type-1 query format that is used internally. And + to do this, the generic front-end's own configuration file must be + used. This file is described + elsewhere; + the salient point for SRU and SRW support is that + zebrasrv + must be started with the + -f frontendConfigFile + option rather than the + -c zebraConfigFile + option, + and that the front-end configuration file must include both a + reference to the Zebra configuration file and the CQL-to-PQF + translator configuration file. + + + A minimal front-end configuration file that does this would read as + follows: + + + + zebra.cfg + ../../tab/pqf.properties + + +]]> + + The + <config> + element contains the name of the Zebra configuration file that was + previously specified by the + -c + command-line argument, and the + <cql2rpn> + element contains the name of the CQL properties file specifying how + various CQL indexes, relations, etc. are translated into Type-1 + queries. + SRU and SRW Protocol Support and Behavior - Placeholder for DocBook's facist schema x + ### x-pquery