X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fserver.xml;h=52b0bc2544ddb6e40339958a5c1510f2a7dfac4a;hb=bfd4dd0d44c779d699f7a1b32e72744733f02caf;hp=c39b4ab24453df92f499bf409c2af0619b7408c3;hpb=be1ed58119bbbc6063723f1a255ab67e18885d8f;p=idzebra-moved-to-github.git diff --git a/doc/server.xml b/doc/server.xml index c39b4ab..52b0bc2 100644 --- a/doc/server.xml +++ b/doc/server.xml @@ -1,5 +1,5 @@ - + The Z39.50 Server @@ -16,7 +16,7 @@ zebrasrv manpage --> - DESCRIPTION + Description Zebra is a high-performance, general-purpose structured text indexing and retrieval engine. It reads structured records in a variety of input formats (eg. email, XML, MARC) and allows access to them through exact @@ -36,12 +36,12 @@ - SYNOPSIS + Synopsis &zebrasrv-synopsis; - OPTIONS + Options The options for zebrasrv are the same @@ -52,19 +52,13 @@ &zebrasrv-options; - VIRTUAL HOSTS - - zebrasrv uses the YAZ server frontend and does - support multiple virtual servers behind multiple listening sockets. - - &zebrasrv-virtual; - - FILES + + Files zebra.cfg - SEE ALSO + See Also zebraidx @@ -76,18 +70,6 @@ - Section "The Z39.50 Server" in the Zebra manual. - http://www.indexdata.dk/zebra/doc/server.tkl - - - Section "Virtual Hosts" in the YAZ manual. - http://www.indexdata.dk/yaz/doc/server.vhosts.tkl - - - Section "Specification of CQL to RPN mappings" in the YAZ manual. - http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map - - The Zebra software is Copyright Index Data http://www.indexdata.dk and distributed under the @@ -593,21 +575,26 @@ 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/SRW Server (zebrasrv) + Running the SRU Server (zebrasrv) 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 + 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 and SRW requests; but since it + 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 or SRW search Zebra with + It is possible to cheat, by having SRU search Zebra with a PQF query instead of CQL, using the x-pquery parameter instead of @@ -622,11 +609,11 @@ browser to: - http://localhost:9999/Default?version=1.1& - operation=searchRetrieve& - x-pquery=mineral& - startRecord=1& - maximumRecords=1 + 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 @@ -643,7 +630,7 @@ 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 + the salient point for SRU support is that zebrasrv must be started with the -f frontendConfigFile @@ -678,11 +665,204 @@ 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 + SRU and SRW Protocol Support and Behavior - ### x-pquery + + 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, + ). + A PQF query is submitted by using the extension parameter + x-pquery, + in which case the + query + parameter must be omitted, which makes the request not valid SRU. + Please don't do this. + + + + + Scan + + Zebra does not support SRU's + scan + operation, as described at + + + + This is a rather embarrassing surprise as the pieces are all + there: Z39.50 scan is supported, and SRU scan requests are + recognised and diagnosed. To add further to the embarrassment, a + mutant form of SRU scan is supported, using + the non-standard x-pScanClause parameter in + place of the standard scanClause to scan on a + PQF query clause. + + + + + Explain + + Zebra fully supports SRU's core + explain + operation, as described at + + + + The ZeeRex record explaining a database may be requested either + with a fully fledged SRU request (with + operation=explain + and version-number specified) + or with a simple HTTP GET at the server's basename. + The ZeeRex record returned in response is the one embedded + in the YAZ Frontend Server configuration file that is described in the + Virtual Hosts documentation. + + + Unfortunately, the data found in the + CQL-to-PQF text file must be added by hand-craft into the explain + section of the YAZ Frontend Server configuration file to be able + to provide a suitable explain record. + Too bad, but this is all extreme + new alpha stuff, and a lot of work has yet to be done .. + + + There is no linkeage whatsoever between the Z39.50 explain model + and the SRU/SRW explain response (well, at least not implemented + in Zebra, that is ..). Zebra does not provide a means using + Z39.50 to obtain the ZeeRex record. + + + + + Some SRU Examples + + Surf into http://localhost:9999 + to get an explain response, or use + + + + See number of hits for a query + + + + Fetch record 5-7 in Dublin Core format + + + + Even search using PQF queries using the extended naughty + verb x-pquery + + + + Or scan indexes using the extended extremely naughty + verb x-pScanClause + + Don't do this in production code! + But it's a great fast debugging aid. + + + + + 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. + +