From b014345252c770fff856df02953cc863c5341a49 Mon Sep 17 00:00:00 2001 From: Marc Cromme Date: Thu, 7 Feb 2008 12:36:35 +0000 Subject: [PATCH] added section on SRU CQL webservice added section on Z39.50 protocol --- doc/tutorial.xml | 362 ++++++++++++++++++++++-------------------------------- 1 file changed, 148 insertions(+), 214 deletions(-) diff --git a/doc/tutorial.xml b/doc/tutorial.xml index fbbd8c3..3d8ecb3 100644 --- a/doc/tutorial.xml +++ b/doc/tutorial.xml @@ -1,5 +1,5 @@ - + Tutorial @@ -258,9 +258,9 @@ Investigating the content of the indexes - How works the magic? What is inside the indexes? Why is a certain + How doess the magic work? What is inside the indexes? Why is a certain record foound by a search, and another not?. The answer is in the - inverterd indexes. You can easily investigat them using the + inverterd indexes. You can easily investigate them using the special &zebra; schema zebra::index::fieldname. In this example you can see that the dc_title index has both word @@ -305,11 +305,100 @@ + + Setting up a correct &acro.sru; web service + + + The &acro.sru; specification mandates that the &acro.cql; query + language is supported and properly configure. Also, the server + needs to be able to emmit a proper &acro.explain; &acro.xml; + record, which is used to determine the capabilities of the + specific server instance. + + + + In this example configuration we expoit the similarities between + the &acro.explain; record and the &acro.cql; query language + configuration, we generate the later from the former using an + &acro.xslt; transformation. + + xsltproc conf/explain2cqlpqftxt.xsl conf/explain.xml > conf/cql2pqf.txt + + + + + The we are all set to start the &acro.sru;/acro.z3950; server including + &acro.pqf; and &acro.cql; query configuration. It uses the &yaz; frontend + server configuration - just type + + zebrasrv -f conf/yazserver.xml + + + + + First, we'd like to be sure that we can see the &acro.explain; + &acro.xml; response correctly. You might use either of these equivalent + requests: + http://localhost:9999 + + + http://localhost:9999/?version=1.1&operation=explain + + + + + + Now we can issue true &acro.sru; requests. For example, + dc.title=the + and dc.description=fish results in the following page + + http://localhost:9999/?version=1.1&operation=searchRetrieve&query=dc.title=the + and dc.description=fish &startRecord=1&maximumRecords=1&recordSchema=dc + + + + + Scan of indexes is a part of the &acro.sru; server business. For example, + scanning the dc.title index gives us an idea + what search terms are found there + + http://localhost:9999/?version=1.1&operation=scan&scanClause=dc.title=fish + , + whereas + +http://localhost:9999/?version=1.1&operation=scan&scanClause=dc.identifier=fish + + accesses the indexed indentifiers. + + + + In addition, all &zebra; internal special elemen sets or record + schema's of the form + zebra:: just work right out of the box + + http://localhost:9999/?version=1.1&operation=searchRetrieve&query=dc.title=the + and dc.description=fish &startRecord=1&maximumRecords=1&recordSchema=zebra::snippet + + + + + + + Searching the &acro.oai; database by &acro.z3950; protocol - In this section we repeat the searches and presents we have done so far using the binary &acro.z3950; protocol, you can use any @@ -336,7 +425,7 @@ - Z39.50 presents using presentation stylesheets: + &acro.z3950; presents using presentation stylesheets: Z> elements dc Z> show 2+1 @@ -347,7 +436,7 @@ - Z39.50 buildin Zebra presents (in this configuration only if + &acro.z3950; buildin Zebra presents (in this configuration only if started without yaz-frontendserver): @@ -368,15 +457,15 @@ Z> show 7+1 Z> elements zebra::facet::any:w - Z> show 8+1 + Z> show 1+1 - Z> elements zebra::facet::any:w,dc_title:w - Z> show 9+1 + Z> elements zebra::facet::dc_publisher:p,dc_title:p + Z> show 1+1 - Z39.50 searches targeted at specific indexes and boolean + &acro.z3950; searches targeted at specific indexes and boolean combinations of these can be issued as well. @@ -384,7 +473,7 @@ Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4 Z> show 1+1 - Z> find @attr 1=oai_datestamp @attr 4=3 2001-04-20 + Z> find @attr 1=oai_datestamp @attr 4=3 2001-04-20 Z> show 1+1 Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562 @@ -400,239 +489,84 @@ etc, etc. - - Notice that all indexes defined by 'type="0"' in the - indexing style sheet must be searched using the '@attr 4=3' - structure attribute instruction. - - - Notice also that searching and scan on indexes - 'dc_contributor', 'dc_language', 'dc_rights', and 'dc_source' - might fail, simply because none of the records in the small example set - have these fields set, and consequently, these indexes might not - been created. + &acro.z3950; scan: + + yaz-client localhost:9999 + Z> format xml + Z> querytype prefix + Z> scan @attr 1=oai_identifier @attr 4=3 oai + Z> scan @attr 1=oai_datestamp @attr 4=3 1 + Z> scan @attr 1=oai_setspec @attr 4=3 2000 + Z> + Z> scan @attr 1=dc_title communication + Z> scan @attr 1=dc_identifier @attr 4=3 a + - - - - - - - Setting up a correct &acro.sru; web service - Or, alternatively, starting the SRU/SRW/Z39.50 server including - PQF and CQL query configuration: + &acro.z3950; search using server-side CQL conversion: - zebrasrv -f yazserver.xml - - - - - - - - -Z39.50 scan using server side CQL conversion: - - Unfortunately, this will _never_ work as it is not supported by the - Z39.50 standard. + + + &acro.z3950; scan using server side CQL conversion - + unfortunately, this will _never_ work as it is not supported by the + &acro.z3950; standard. If you want to use scan using server side CQL conversion, you need to make an SRW connection using yaz-client, or a SRU connection using REST Web Services - any browser will do. + + + + + All indexes defined by 'type="0"' in the + indexing style sheet must be searched using the '@attr 4=3' + structure attribute instruction. + + -SRU Explain ZeeRex response: - - http://localhost:9999/ - http://localhost:9999/?version=1.1&operation=explain - - -SRU Search Retrieve records: - - http://localhost:9999/?version=1.1&operation=searchRetrieve - &x-pquery=creator=adam - - http://localhost:9999/?version=1.1&operation=searchRetrieve - &x-pquery=date=1978-01-01 - &startRecord=1&maximumRecords=1&recordSchema=dc - - http://localhost:9999/?version=1.1&operation=searchRetrieve - &x-pquery=dc.title=the - - http://localhost:9999/?version=1.1&operation=searchRetrieve - &x-pquery=description=the - - - relation tests: - - http://localhost:9999/?version=1.1&operation=searchRetrieve - &x-pquery=title%3Cthe - - -SRU scan: - - http://localhost:9999/?version=1.1&operation=scan&scanClause=title=a - http://localhost:9999/?version=1.1&operation=scan - &scanClause=identifier%20eq%20a - - Notice: you need to use the 'eq' relation for all @attr 4=3 indexes - - - -SRW explain with CQL index points: - - Z> open http://localhost:9999 - Z> explain - - Notice: when opening a connection using the 'http.//' prefix, yaz-client - uses SRW SOAP connections, and 'form xml' and 'querytype cql' are - implicitely set. - - -SRW search using implicit server side CQL: - - Z> open http://localhost:9999 - Z> find identifier eq - "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78" - Z> find description < the - - - In SRW connection mode, the follwing fails due to problem in yaz-client: - Z> elements dc - Z> s 1+1 - - -SRW scan using implicit server side CQL: - - yaz-client http://localhost:9999 - Z> scan title = communication - Z> scan identifier eq a - - Notice: you need to use the 'eq' relation for all @attr 4=3 indexes - + + Notice that searching and scan on indexes + dc_contributor, dc_language, + dc_rights, and dc_source + might fail, simply because none of the records in the small example set + have these fields set, and consequently, these indexes might not + been created. + + + ---> -- 1.7.10.4