Chapter 12. The SRU/SRW Server

Table of Contents

1. Running the SRU Server (zebrasrv)
2. SRU and SRW Protocol Support and Behavior
2.1. Search and Retrieval
2.2. Scan
2.3. Explain
2.4. Some SRU Examples
2.5. Initialization, Present, Sort, Close

In addition to Z39.50, Zebra supports the more recent and web-friendly IR protocol SRU, described at http://www.loc.gov/sru. 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 http://www.loc.gov/srw. 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.

1. 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.

Note

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:

	<yazgfs>
	  <server>
	    <config>zebra.cfg</config>
	    <cql2rpn>../../tab/pqf.properties</cql2rpn>
	  </server>
	</yazgfs>

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.

A zebra server running with such a configuration can then be queried using proper, conformant SRU URLs with CQL queries:

	http://localhost:9999/Default?version=1.1
		&operation=searchRetrieve
		&query=title=utah and description=epicent*
		&startRecord=1
		&maximumRecords=1