X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fserver.xml;h=83a5e3c626fd17b216e8fedb7f4027eb0184274b;hb=b367b4068098c28aa284c447edf42ba2c8d7c42b;hp=a4dd5340db6b348fd7547fc773d40dfeab189c4f;hpb=f9ba2efb65f7f9835bc454a55586c285d5385ecb;p=idzebra-moved-to-github.git
diff --git a/doc/server.xml b/doc/server.xml
index a4dd534..83a5e3c 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 HOSTSzebrasrv uses the YAZ server frontend and does
support multiple virtual servers behind multiple listening sockets.
@@ -556,17 +556,234 @@
-
+The SRU/SRW Server
-
-
- Running the SRU/SRW Server (zebrasrv)
- Placeholder for DocBook's facist schema
+
+ 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.
+
+
+ From here on, ``SRU'' is used to indicate both the SRU and SRW
+ protocols, as they are identical except for the transport used for
+ the protocol packets and Zebra's support for them is equivalent.
+
+
+
+ Running the SRU Server (zebrasrv)
+
+ Because Zebra supports all three protocols on one port, it would
+ seem to follow that the SRU 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 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 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 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
+
+ Zebra running as an SRU server supports SRU version 1.1, including
+ CQL version 1.1. In particular, it provides support for the
+ following elements of the protocol.
+
+
+
+ Search and Retrieval
+
+ Zebra fully supports SRU's core
+ searchRetrieve
+ operation, as described at
+
+
+
+ One of the great strengths of SRU is that it mandates a standard
+ query language, CQL, and that all conforming implementations can
+ therefore be trusted to correctly interpret the same queries. It
+ is with some shame, then, that we admit that Zebra also supports
+ an additional query language, our own Prefix Query Format (PQF,
+ ).
+x-pquery
+
+
+
+
+
+
+ Scan
+
+ ###
+
+
+
+
+ Explain
+
+ ###
+
+
+
+
+ Initialization, Present, Sort, Close
+
+ In the Z39.50 protocol, Initialization, Present, Sort and Close
+ are separate operations. In SRU, however, these operations do not
+ exist.
+
+
+
+
+ SRU has no explicit initialization handshake phase, but
+ commences immediately with searching, scanning and explain
+ operations.
+
+
+
+
+ Neither does SRU have a close operation, since the protocol is
+ stateless and each request is self-contained. (It is true that
+ multiple SRU request/response pairs may be implemented as
+ multiple HTTP request/response pairs over a single persistent
+ TCP/IP connection; but the closure of that connection is not a
+ protocol-level operation.)
+
+
+
+
+ Retrieval in SRU is part of the
+ searchRetrieve operation, in which a search
+ is submitted and the response includes a subset of the records
+ in the result set. There is no direct analogue of Z39.50's
+ Present operation which requests records from an established
+ result set. In SRU, this is achieved by sending a subsequent
+ searchRetrieve request with the query
+ cql.resultSetId=id where
+ id is the identifier of the previously
+ generated result-set.
+
+
+
+
+ Sorting in CQL is done within the
+ searchRetrieve operation - in v1.1, by an
+ explicit sort parameter, but the forthcoming
+ v1.2 or v2.0 will most likely use an extension of the query
+ language, CQL for sorting: see
+
+
+
+
+
+ It can be seen, then, that while Zebra operating as an SRU server
+ does not provide the same set of operations as when operating as a
+ Z39.50 server, it does provide equivalent functionality.
+
+