From 19f3ea2eccaeb7e16c2807b07c6243f66405c6bc Mon Sep 17 00:00:00 2001 From: Marc Cromme Date: Tue, 5 Feb 2008 10:15:58 +0000 Subject: [PATCH] added lot of examples --- doc/tutorial.xml | 365 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 293 insertions(+), 72 deletions(-) diff --git a/doc/tutorial.xml b/doc/tutorial.xml index b336ac1..665c752 100644 --- a/doc/tutorial.xml +++ b/doc/tutorial.xml @@ -1,5 +1,5 @@ - + Tutorial @@ -19,17 +19,35 @@ /usr/share/idzebra-2.0.-examples/oai-pmh. An XML file containing multiple &acro.oai; records is located in the sub - directory examples/oai-pmh/data. To index these, type: + directory examples/oai-pmh/data. + + + Additional OAI test records can be downloaded by running a shell + script (you may want to abort the script when you have waitet + longer than your coffe brews ..). + + cd data + ./fetch_OAI_data.sh + cd ../ + + + + To index these &acro.oai; records, type: - zebraidx -c conf/zebra.cfg init - zebraidx -c conf/zebra.cfg update data/oai-caltech.xml - zebraidx -c conf/zebra.cfg commit + zebraidx-2.0 -c conf/zebra.cfg init + zebraidx-2.0 -c conf/zebra.cfg update data/oai-caltech.xml + zebraidx-2.0 -c conf/zebra.cfg commit In case you have not installed zebra yet but have compiled the binaries from this tarball, use the following command form: ../../index/zebraidx -c conf/zebra.cfg this and that + On some systems the &zebra; binaries are installed under the + generic names, you need to use the following command form: + + zebraidx -c conf/zebra.cfg this and that + @@ -57,7 +75,7 @@ If your indexing command was successful, you are now ready to fire up a server. To start a server on port 9999, type: - zebrasrv -c conf/zebra.cfg @:9999 + zebrasrv-2.0 -c conf/zebra.cfg @:9999 @@ -66,32 +84,282 @@ named Default. The database contains several &acro.oai; records, and the server will return records in the &acro.xml; format only. The indexing machine - di the splitting into individual records just behind the scenes. + did the splitting into individual records just behind the scenes. - - To test the server, you can use any &acro.z3950; client. - For instance, you can use the demo command-line client that comes - with &yaz;; we start the SRU/SRW/Z39.50 server in PQF mode only: - - - - yaz-client localhost:9999 - - - - - When the client has connected, you can type: - + + + + + Searching the &acro.oai; database by web service + + + &zebra; has a build-in web service, which is close to the + &acro.sru; standard web service. We use it to access our new + database using any &acro.xml; enabled web browser. + This service is using the &acro.pqf; query language. + In a later + section we show how to run a fully compliant &acro.sru; server, + including support for the query language &acro.cql; + + + + Searching and retrieving &acro.xml; records is easy. For example, + you can point your browser to one of the following url's to + search for the term the. Just point your + browser at this link: + + http://localhost:9999/?version=1.1&operation=searchRetrieve&query=the + + + + + These URL's woun't work unless you have indexed the example data + and started an &zebra; server as outlined in the previous section. + + + + + In case we actually want to retrieve one record, we need to alter + our URl to the following + + http://localhost:9999/?version=1.1&operation=searchRetrieve&query=the&startRecord=1&maximumRecords=1&recordSchema=dc + + + + + This way we can page through our result set in chunks of records, + for example, we access the 6th to the 10th record using the URL + + http://localhost:9999/?version=1.1&operation=searchRetrieve&query=the&startRecord=6&maximumRecords=5&recordSchema=dc + + + + + + + + + + + Presenting search results in different formats + + + +Z39.50 search: + + yaz-client localhost:9999 Z> format xml + Z> querytype prefix Z> elements oai Z> find the Z> show 1+1 - - + + +Z39.50 presents using presentation stylesheets: + + Z> elements dc + Z> show 2+1 + + Z> elements zebra + Z> show 3+1 + + +Z39.50 buildin Zebra presents (in this configuration only if + started without yaz-frontendserver): + + + Z> elements zebra::meta + Z> show 4+1 + + Z> elements zebra::meta::sysno + Z> show 5+1 + + Z> format sutrs + Z> show 5+1 + Z> format xml + + Z> elements zebra::index + Z> show 6+1 + + Z> elements zebra::snippet + Z> show 7+1 + + Z> elements zebra::facet::any:w + Z> show 8+1 + + Z> elements zebra::facet::any:w,dc_title:w + Z> show 9+1 + + + + +Z39.50 searches targeted at specific indexes + + Z> elements zebra + 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> show 1+1 + + Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562 + Z> show 1+1 + + Z> find @attr 1=dc_title communication + Z> show 1+1 + + Z> find @attr 1=dc_identifier @attr 4=3 + http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86 + Z> show 1+1 + + 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' + fails, simply because none of the records in this example set + have these fields set, and consequently, these indexes are + _not_ created. + + + + + + + + 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 + &acro.z3950; client. + For instance, you can use the demo command-line client that comes + with &yaz;. + + + Connecting to the server is done by the command + + yaz-client localhost:9999 + + + + + When the client has connected, you can type: + + Z> format xml + Z> querytype prefix + Z> elements oai + Z> find the + Z> show 1+1 + + + + + Z39.50 presents using presentation stylesheets: + + Z> elements dc + Z> show 2+1 + + Z> elements zebra + Z> show 3+1 + + + + + Z39.50 buildin Zebra presents (in this configuration only if + started without yaz-frontendserver): + + + Z> elements zebra::meta + Z> show 4+1 + + Z> elements zebra::meta::sysno + Z> show 5+1 + + Z> format sutrs + Z> show 5+1 + Z> format xml + + Z> elements zebra::index + Z> show 6+1 + + Z> elements zebra::snippet + Z> show 7+1 + + Z> elements zebra::facet::any:w + Z> show 8+1 + + Z> elements zebra::facet::any:w,dc_title:w + Z> show 9+1 + + + + + Z39.50 searches targeted at specific indexes and boolean + combinations of these can be issued as well. + + + Z> elements dc + 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> show 1+1 + + Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562 + Z> show 1+1 + + Z> find @attr 1=dc_title communication + Z> show 1+1 + + Z> find @attr 1=dc_identifier @attr 4=3 + http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86 + Z> show 1+1 + + 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. + + + + + + + + Setting up a correct &acro.sru; web service + +Or, alternatively, starting the SRU/SRW/Z39.50 server including +PQF and CQL query configuration: + + zebrasrv -f yazserver.xml + + + + - - - - - - Requesting &acro.oai; records in &zebra; specific formats - - - -- 1.7.10.4