<?xml version="1.0" encoding="UTF-8"?>
<section id="ajaxdev">
- <title>Ajax client development</title>
-
- <para>
- Pazpar2 offers programmer a simple Web Service protocol that can be used (queried in a request/response fashion) from any, server- or client-side, programming language with an XML support. However, when programming a Web-based client to Pazpar2, to achieve certain level of interactivity and instant notification of latest changes in the result set, Ajax (Asynchronous JavaScript and XML) technology may be used. An Ajax client allows user to browse the results before the lengthy process of information retrieval from the back-end targets is finished. Blocking and waiting for usually slow back-end targets is one of the biggest functionality issues in a federated search engine.
- </para>
-
- <para><bridgehead>Pz2.js</bridgehead></para>
-
- <para>
- Pazpar2 comes with a small JavaScript library called pz2.js. This library is designed to simplify development of an Ajax-based pazpar2 client and alleviate programmer from the low-level details like polling the web service, fetching and parsing returned XML output or managing timers, sessions and basic state variables.
- </para>
-
- <para>
- The library supports most major browsers including Firefox 1.5+, IE 6+, Safari 2+, Opera 9+ and Konqueror.
- </para>
-
- <para>
- The library can work in two modes: a session-aware mode and a session-less mode.
- </para>
+ <title>Ajax client development</title>
+
+ <para>
+ Pazpar2 offers programmer a simple Web Service protocol that can be
+ used (queried in a request/response fashion) from any, server- or
+ client-side, programming language with an XML support. However, when
+ programming a Web-based client to Pazpar2, to achieve certain level of
+ interactivity and instant notification of latest changes in the result
+ set, Ajax (Asynchronous JavaScript and XML) technology may be used. An
+ Ajax client allows user to browse the results before the lengthy
+ process of information retrieval from the back-end targets is
+ finished. Blocking and waiting for usually slow back-end targets is
+ one of the biggest functionality issues in a federated search engine.
+ </para>
- <para>In the session-aware mode, the library assumes that the pazpar2 daemon is contacted directly (preferably via Apache proxy to avoid security breaches) and tracks the session Ids internally.
- </para>
-
- <para>In the session-less mode the library assumes that the client is identified on the server and the session Ids are not managed directly. This way of operation requires more sophisticated pazpar2 proxy (preferably a wrapper written in a server-side scripting language like PHP that can identify clients and relate them to open pazpar2 sessions).</para>
-
- <para><bridgehead>Using pz2.js</bridgehead></para>
-
- <para>
- Client development with the pz2.js is strongly event based and the style should be familiar to most JavaScript developers. A simple client (jsdemo) is distributed with pazpar2's source code and shows how to set-up and use pz2.js.
- </para>
-
- <para>
- In short, programmer starts by instantiating the pz2 object and passing an array of parameters to the constructor. The parameter array specifies callbacks used for handling responses to the pazpar2 commands. Additionally, the parameter array is used to configure run-time parameters of the pz2.js like polling timer time-outs, session-mode and XSLT style-sheets.
- </para>
-
- <para><bridgehead>Command callbacks</bridgehead></para>
-
- <para>
- Callback naming is simple and follows “on” prefix plus command name scheme (like onsearch, onshow, onrecord, ... etc.). When programmer calls a function like show or record on the pz2 object, pz2.js will keep on polling pazpar2 (until the backend targets are idle) and with each command's response an assigned callback will be called. In case of pazpar2's internal error an error callback is called.
- </para>
-
- <screen>
+ <para><bridgehead>Pz2.js</bridgehead></para>
+
+ <para>
+ Pazpar2 comes with a small JavaScript library called pz2.js. This
+ library is designed to simplify development of an Ajax-based pazpar2
+ client and alleviate programmer from the low-level details like
+ polling the web service, fetching and parsing returned XML output or
+ managing timers, sessions and basic state variables.
+ </para>
+
+ <para>
+ The library supports most major browsers including Firefox 1.5+, IE
+ 6+, Safari 2+, Opera 9+ and Konqueror.
+ </para>
+
+ <para>
+ The library can work in two modes: a session-aware mode and a
+ session-less mode.
+ </para>
+
+ <para>
+ In the session-aware mode, the library assumes that the pazpar2
+ daemon is contacted directly (preferably via Apache proxy to avoid
+ security breaches) and tracks the session Ids internally.
+ </para>
+
+ <para>
+ In the session-less mode the library assumes that the client is
+ identified on the server and the session Ids are not managed
+ directly. This way of operation requires more sophisticated pazpar2
+ proxy (preferably a wrapper written in a server-side scripting
+ language like PHP that can identify clients and relate them to open
+ pazpar2 sessions).
+ </para>
+
+ <para><bridgehead>Using pz2.js</bridgehead></para>
+
+ <para>
+ Client development with the pz2.js is strongly event based and the
+ style should be familiar to most JavaScript developers. A simple
+ client (jsdemo) is distributed with pazpar2's source code and shows
+ how to set-up and use pz2.js.
+ </para>
+
+ <para>
+ In short, programmer starts by instantiating the pz2 object and
+ passing an array of parameters to the constructor. The parameter array
+ specifies callbacks used for handling responses to the pazpar2
+ commands. Additionally, the parameter array is used to configure
+ run-time parameters of the pz2.js like polling timer time-outs,
+ session-mode and XSLT style-sheets.
+ </para>
+
+ <para><bridgehead>Command callbacks</bridgehead></para>
+
+ <para>
+ Callback naming is simple and follows “on” prefix plus command name
+ scheme (like onsearch, onshow, onrecord, ... etc.). When programmer
+ calls a function like show or record on the pz2 object, pz2.js will
+ keep on polling pazpar2 (until the backend targets are idle) and with
+ each command's response an assigned callback will be called. In case
+ of pazpar2's internal error an error callback is called.
+ </para>
+
+ <screen>
my_paz = new pz2 (
{
- "pazpar2path": "/pazpar2/search.pz2",
- "usesessions" : true,
-
- // assigning command handler, turns on automatic polling
- "onshow": my_onshow,
- // polling period for each command can be specified
- "showtime": 500,
-
- "onterm": my_onterm,
- // facet terms are specified as a comma separated list
- "termlist": "subject,author",
-
- "onrecord": my_onrecord
- }
- );
- </screen>
-
- <para>
- Each command callback is a user defined function that takes a hash object as a parameter. The hash object contains parsed pazpar2 responses (hash members that correspond to the elements in the response XML document). Within the handler programmer further processes the data and updates the viewed document.
- </para>
-
- <screen>
- function my_onstat(data) {
- var stat = document.getElementById("stat");
- stat.innerHTML = '<span>Active clients: '+ data.activeclients
- + '/' + data.clients + ' | </span>'
- + '<span>Retrieved records: ' + data.records
- + '/' + data.hits + '</span>';
- }
-
- function my_onshow(data) {
- // data contains parsed show response
- for (var i = 0; i < data.hits[0].length; i++)
- // update page with the hits
- }
-
- function on_record(data) {
- // if detailsstylesheet parameter was set data array
- // will contain raw xml and xsl data
- Element_appendTransformResult(someDiv, data.xmlDoc, data.xslDoc);
- }
- </screen>
-
- <para><bridgehead>pz2.js on runtime</bridgehead></para>
-
- <para>
- The search process is initiated by calling the search method on the instantiated pz2 object. To initiate short status reports and per-target status information methods stat and bytarget have to be called accordingly.
- </para>
+ "pazpar2path": "/pazpar2/search.pz2",
+ "usesessions" : true,
- <screen>
- my_paz.search (query, recPergPage, 'relevance');
- </screen>
+ // assigning command handler, turns on automatic polling
+ "onshow": my_onshow,
+ // polling period for each command can be specified
+ "showtime": 500,
- <para>
- Managing the results (keeping track of the browsed results page and sorting) is up to the client's programmer. At any point the show method may be called to bring up the latest result set with a different sorting criteria or range and without re-executing the search on the back-end.
- </para>
+ "onterm": my_onterm,
+ // facet terms are specified as a comma separated list
+ "termlist": "subject,author",
- <screen>
- my_paz.show (1, 10, 'relevance');
- </screen>
-
- <para>
- To retrieve a detailed record the record command is called. When calling record command one may temporarily override its default callback by specifying the handler parameter. This might be useful when retrieving raw records that need to be processed differently.
- </para>
-
- <screen>
- my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
- </screen>
+ "onrecord": my_onrecord
+ }
+ );
+ </screen>
+
+ <para>
+ Each command callback is a user defined function that takes a hash
+ object as a parameter. The hash object contains parsed pazpar2
+ responses (hash members that correspond to the elements in the
+ response XML document). Within the handler programmer further
+ processes the data and updates the viewed document.
+ </para>
+
+ <screen>
+ function my_onstat(data) {
+ var stat = document.getElementById("stat");
+ stat.innerHTML = '<span>Active clients: '+ data.activeclients
+ + '/' + data.clients + ' | </span>'
+ + '<span>Retrieved records: ' + data.records
+ + '/' + data.hits + '</span>';
+ }
+
+ function my_onshow(data) {
+ // data contains parsed show response
+ for (var i = 0; i < data.hits[0].length; i++)
+ // update page with the hits
+ }
+
+ function on_record(data) {
+ // if detailsstylesheet parameter was set data array
+ // will contain raw xml and xsl data
+ Element_appendTransformResult(someDiv, data.xmlDoc, data.xslDoc);
+ }
+ </screen>
+
+ <para><bridgehead>pz2.js on runtime</bridgehead></para>
+
+ <para>
+ The search process is initiated by calling the search method on the
+ instantiated pz2 object. To initiate short status reports and
+ per-target status information methods stat and bytarget have to be
+ called accordingly.
+ </para>
+
+ <screen>
+ my_paz.search (query, recPergPage, 'relevance');
+ </screen>
+
+ <para>
+ Managing the results (keeping track of the browsed results page and
+ sorting) is up to the client's programmer. At any point the show
+ method may be called to bring up the latest result set with a
+ different sorting criteria or range and without re-executing the
+ search on the back-end.
+ </para>
+
+ <screen>
+ my_paz.show (1, 10, 'relevance');
+ </screen>
- <variablelist>
-
- <para><bridgehead>PARAMATERS ARRAY</bridgehead></para>
+ <para>
+ To retrieve a detailed record the record command is called. When
+ calling record command one may temporarily override its default
+ callback by specifying the handler parameter. This might be useful
+ when retrieving raw records that need to be processed differently.
+ </para>
+
+ <screen>
+ my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
+ </screen>
+
+ <variablelist>
+
+ <para><bridgehead>PARAMATERS ARRAY</bridgehead></para>
- <varlistentry><term>pazpar2path</term>
- <listitem><para>server path to pazpar2 (relative to the portal), when pazpar2 is installed as a package this does not have to be set </para></listitem>
- </varlistentry>
+ <varlistentry><term>pazpar2path</term>
+ <listitem><para>server path to pazpar2 (relative to the portal), when pazpar2 is installed as a package this does not have to be set </para></listitem>
+ </varlistentry>
- <varlistentry><term>usesessions</term>
- <listitem><para>boolean, when set to true pz2.js will manage sessions internally otherwise it's left to the server-side script, default true</para></listitem>
- </varlistentry>
+ <varlistentry><term>usesessions</term>
+ <listitem><para>boolean, when set to true pz2.js will manage sessions internally otherwise it's left to the server-side script, default true</para></listitem>
+ </varlistentry>
- <varlistentry><term>autoInit</term>
- <listitem><para>bolean, sets auto initialization of pazpar2 session on the object instantiation, default true, valid only if usesession is set to true</para></listitem>
- </varlistentry>
+ <varlistentry><term>autoInit</term>
+ <listitem><para>bolean, sets auto initialization of pazpar2 session on the object instantiation, default true, valid only if usesession is set to true</para></listitem>
+ </varlistentry>
- <varlistentry><term>detailstylesheet</term>
- <listitem><para>path to the xsl presentation stylesheet (relative to the portal) used for the detailed record display</para></listitem></varlistentry>
-
- <varlistentry><term>errorhandler</term>
- <listitem><para>callback function called on any, pazpar2 or pz2.js' internal, error</para></listitem></varlistentry>
+ <varlistentry><term>detailstylesheet</term>
+ <listitem><para>path to the xsl presentation stylesheet (relative to the portal) used for the detailed record display</para></listitem></varlistentry>
+
+ <varlistentry><term>errorhandler</term>
+ <listitem><para>callback function called on any, pazpar2 or pz2.js' internal, error</para></listitem></varlistentry>
- <varlistentry><term>oninit</term>
- <listitem><para>specifies init response callback function</para></listitem></varlistentry>
+ <varlistentry><term>oninit</term>
+ <listitem><para>specifies init response callback function</para></listitem></varlistentry>
- <varlistentry><term>onstat</term>
- <listitem><para>specifies stat response callback function</para></listitem></varlistentry>
+ <varlistentry><term>onstat</term>
+ <listitem><para>specifies stat response callback function</para></listitem></varlistentry>
- <varlistentry><term>onshow</term>
- <listitem><para>specifies show response callback function</para></listitem></varlistentry>
+ <varlistentry><term>onshow</term>
+ <listitem><para>specifies show response callback function</para></listitem></varlistentry>
- <varlistentry><term>onterm</term>
- <listitem><para>specifies termlist response callback function</para></listitem></varlistentry>
+ <varlistentry><term>onterm</term>
+ <listitem><para>specifies termlist response callback function</para></listitem></varlistentry>
- <varlistentry><term>onrecord</term>
- <listitem><para>specifies record response callback function</para></listitem></varlistentry>
+ <varlistentry><term>onrecord</term>
+ <listitem><para>specifies record response callback function</para></listitem></varlistentry>
- <varlistentry><term>onbytarget</term>
- <listitem><para>specifies bytarget response callback function</para></listitem></varlistentry>
+ <varlistentry><term>onbytarget</term>
+ <listitem><para>specifies bytarget response callback function</para></listitem></varlistentry>
- <varlistentry><term>onreset</term>
- <listitem><para>specifies reset method callback function</para></listitem></varlistentry>
+ <varlistentry><term>onreset</term>
+ <listitem><para>specifies reset method callback function</para></listitem></varlistentry>
- <varlistentry><term>termlist</term>
- <listitem><para>comma separated list of facets</para></listitem></varlistentry>
+ <varlistentry><term>termlist</term>
+ <listitem><para>comma separated list of facets</para></listitem></varlistentry>
- <varlistentry><term>keepAlive</term>
- <listitem><para>ping period, should not be lower than 5000 usec</para></listitem></varlistentry>
+ <varlistentry><term>keepAlive</term>
+ <listitem><para>ping period, should not be lower than 5000 usec</para></listitem></varlistentry>
- <varlistentry><term>stattime</term>
- <listitem><para>default 1000 usec</para></listitem></varlistentry>
+ <varlistentry><term>stattime</term>
+ <listitem><para>default 1000 usec</para></listitem></varlistentry>
- <varlistentry><term>termtime</term></varlistentry>
+ <varlistentry><term>termtime</term></varlistentry>
- <varlistentry><term>showtime</term></varlistentry>
+ <varlistentry><term>showtime</term></varlistentry>
- <varlistentry><term>bytargettime</term></varlistentry>
+ <varlistentry><term>bytargettime</term></varlistentry>
- </variablelist>
+ </variablelist>
- <variablelist>
-
- <para><bridgehead>METHODS</bridgehead></para>
-
- <varlistentry><term>stop ()</term>
- <listitem><para>stop activity by clearing timeouts</para></listitem></varlistentry>
+ <variablelist>
+
+ <para><bridgehead>METHODS</bridgehead></para>
+
+ <varlistentry><term>stop ()</term>
+ <listitem><para>stop activity by clearing timeouts</para></listitem></varlistentry>
- <varlistentry><term>reset ()</term>
- <listitem><para>reset state</para></listitem></varlistentry>
+ <varlistentry><term>reset ()</term>
+ <listitem><para>reset state</para></listitem></varlistentry>
- <varlistentry><term>init (sesionId)</term>
- <listitem><para>session-mode, initialize new session or pick up a session already initialized</para></listitem></varlistentry>
+ <varlistentry><term>init (sesionId)</term>
+ <listitem><para>session-mode, initialize new session or pick up a session already initialized</para></listitem></varlistentry>
- <varlistentry><term>ping ()</term>
- <listitem><para>session-mode, intitialize pinging </para></listitem></varlistentry>
+ <varlistentry><term>ping ()</term>
+ <listitem><para>session-mode, intitialize pinging </para></listitem></varlistentry>
- <varlistentry><term>search (query, num, sort, filter, showfrom)</term>
- <listitem><para>execute piggy-back search and activate polling on every command specified by assigning command callback (in the pz2 constructor)</para></listitem></varlistentry>
+ <varlistentry><term>search (query, num, sort, filter, showfrom)</term>
+ <listitem><para>execute piggy-back search and activate polling on every command specified by assigning command callback (in the pz2 constructor)</para></listitem></varlistentry>
- <varlistentry><term>show (start, num, sort)</term>
- <listitem><para>start or change parameters of polling for a given window of records</para></listitem></varlistentry>
+ <varlistentry><term>show (start, num, sort)</term>
+ <listitem><para>start or change parameters of polling for a given window of records</para></listitem></varlistentry>
- <varlistentry><term>record (id, offset, syntax, handler)</term>
- <listitem><para>retrieve detailed or raw record. handler temporarily overrides default callback function.</para></listitem></varlistentry>
+ <varlistentry><term>record (id, offset, syntax, handler)</term>
+ <listitem><para>retrieve detailed or raw record. handler temporarily overrides default callback function.</para></listitem></varlistentry>
- <varlistentry><term>termlist ()</term>
- <listitem><para>start polling for termlists</para></listitem></varlistentry>
+ <varlistentry><term>termlist ()</term>
+ <listitem><para>start polling for termlists</para></listitem></varlistentry>
- <varlistentry><term>bytarget ()</term>
- <listitem><para>start polling for target status</para></listitem></varlistentry>
+ <varlistentry><term>bytarget ()</term>
+ <listitem><para>start polling for target status</para></listitem></varlistentry>
- <varlistentry><term>stat ()</term>
- <listitem><para>start polling for pazpar2 status</para></listitem></varlistentry>
+ <varlistentry><term>stat ()</term>
+ <listitem><para>start polling for pazpar2 status</para></listitem></varlistentry>
- </variablelist>
-
- <para/>
- <para>Pz2.js comes with a set of cross-browser helper classes and functions.</para>
+ </variablelist>
+
+ <para/>
+ <para>Pz2.js comes with a set of cross-browser helper classes and functions.</para>
- <variablelist>
+ <variablelist>
- <para><bridgehead>Ajax helper class</bridgehead></para>
+ <para><bridgehead>Ajax helper class</bridgehead></para>
- <varlistentry><term>pzHttpRequest</term>
- <listitem><para>a cross-browser Ajax wrapper class</para></listitem></varlistentry>
+ <varlistentry><term>pzHttpRequest</term>
+ <listitem><para>a cross-browser Ajax wrapper class</para></listitem></varlistentry>
- <varlistentry><term>constructor (url, errorHandler)</term>
- <listitem><para>create new request for a given url</para></listitem></varlistentry>
+ <varlistentry><term>constructor (url, errorHandler)</term>
+ <listitem><para>create new request for a given url</para></listitem></varlistentry>
- <varlistentry><term>get (params, callback)</term>
- <listitem><para>asynchronous, send the request with given parameters (array) and call callback with response as parameter</para></listitem></varlistentry>
+ <varlistentry><term>get (params, callback)</term>
+ <listitem><para>asynchronous, send the request with given parameters (array) and call callback with response as parameter</para></listitem></varlistentry>
- <varlistentry><term>post (params, data, callback)</term>
- <listitem><para>asychronous, post arbitrary data (may be XML doc) and call callback with response as parameter</para></listitem></varlistentry>
+ <varlistentry><term>post (params, data, callback)</term>
+ <listitem><para>asychronous, post arbitrary data (may be XML doc) and call callback with response as parameter</para></listitem></varlistentry>
- <varlistentry><term>load ()</term>
- <listitem><para>synchronous, returns the response for the given request</para></listitem></varlistentry>
+ <varlistentry><term>load ()</term>
+ <listitem><para>synchronous, returns the response for the given request</para></listitem></varlistentry>
- </variablelist>
+ </variablelist>
- <variablelist>
+ <variablelist>
- <para><bridgehead>XML helper functions</bridgehead></para>
-
- <varlistentry><term>document.newXmlDoc (root)</term>
- <listitem><para>create new XML document with root node as specified in parameter</para></listitem></varlistentry>
+ <para><bridgehead>XML helper functions</bridgehead></para>
+
+ <varlistentry><term>document.newXmlDoc (root)</term>
+ <listitem><para>create new XML document with root node as specified in parameter</para></listitem></varlistentry>
- <varlistentry><term>document.parseXmlFromString (xmlString)</term>
- <listitem><para>create new XML document from string</para></listitem></varlistentry>
+ <varlistentry><term>document.parseXmlFromString (xmlString)</term>
+ <listitem><para>create new XML document from string</para></listitem></varlistentry>
- <varlistentry><term>document.transformToDoc (xmlDoc, xslDoc)</term>
- <listitem><para>returns new XML document as a result</para></listitem></varlistentry>
+ <varlistentry><term>document.transformToDoc (xmlDoc, xslDoc)</term>
+ <listitem><para>returns new XML document as a result</para></listitem></varlistentry>
- <varlistentry><term>Element_removeFromDoc (DOM_Element)</term>
- <listitem><para>remove element from the document</para></listitem></varlistentry>
+ <varlistentry><term>Element_removeFromDoc (DOM_Element)</term>
+ <listitem><para>remove element from the document</para></listitem></varlistentry>
- <varlistentry><term>Element_emptyChildren (DOM_Element)</term></varlistentry>
+ <varlistentry><term>Element_emptyChildren (DOM_Element)</term></varlistentry>
- <varlistentry><term>Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)</term>
- <listitem><para>append xsl transformation result to a DOM element</para></listitem></varlistentry>
+ <varlistentry><term>Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)</term>
+ <listitem><para>append xsl transformation result to a DOM element</para></listitem></varlistentry>
- <varlistentry><term>Element_appendTextNode (DOM_Element, tagName, textContent)</term>
- <listitem><para>append new text node to the element</para></listitem></varlistentry>
+ <varlistentry><term>Element_appendTextNode (DOM_Element, tagName, textContent)</term>
+ <listitem><para>append new text node to the element</para></listitem></varlistentry>
- <varlistentry><term>Element_setTextContent (DOM_Element, textContent)</term>
- <listitem><para>set text content of the element</para></listitem></varlistentry>
+ <varlistentry><term>Element_setTextContent (DOM_Element, textContent)</term>
+ <listitem><para>set text content of the element</para></listitem></varlistentry>
- <varlistentry><term>Element_getTextContent (DOM_Element)</term>
- <listitem><para>get text content of the element</para></listitem></varlistentry>
+ <varlistentry><term>Element_getTextContent (DOM_Element)</term>
+ <listitem><para>get text content of the element</para></listitem></varlistentry>
- <varlistentry><term>Element_parseChildNodes (DOM_Element)</term>
- <listitem><para>parse all descendants into an associative array</para></listitem></varlistentry>
+ <varlistentry><term>Element_parseChildNodes (DOM_Element)</term>
+ <listitem><para>parse all descendants into an associative array</para></listitem></varlistentry>
- </variablelist>
-
+ </variablelist>
+
</section>
<!-- Keep this comment at the end of the file
- Local variables:
- mode: sgml
- sgml-omittag:t
- sgml-shorttag:t
- sgml-minimize-attributes:nil
- sgml-always-quote-attributes:t
- sgml-indent-step:1
- sgml-indent-data:t
- sgml-parent-document: nil
- sgml-local-catalogs: nil
- sgml-namecase-general:t
- End:
- -->
+Local variables:
+mode: nxml
+nxml-child-indent: 1
+End:
+-->
<inlinemediaobject>
<imageobject>
<imagedata fileref="common/id.png" format="PNG"/>
- </imageobject>
- <imageobject>
- <imagedata fileref="common/id.eps" format="EPS"/>
- </imageobject>
- </inlinemediaobject>
+ </imageobject>
+ <imageobject>
+ <imagedata fileref="common/id.eps" format="EPS"/>
+ </imageobject>
+ </inlinemediaobject>
</simpara>
</abstract>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
-
+
<section id="what.pazpar2.is">
- <title>What Pazpar2 is</title>
- <para>
- Pazpar2 is a stand-alone metasearch engine with a web-service API, designed
- to be used either from a browser-based client (JavaScript, Flash,
- Java applet,
- etc.), from server-side code, or any combination of the two.
- Pazpar2 is a highly optimized client designed to
- search many resources in parallel. It implements record merging,
- relevance-ranking and sorting by arbitrary data content, and facet
- analysis for browsing purposes. It is designed to be data-model
- independent, and is capable of working with MARC, DublinCore, or any
- other <ulink url="&url.xml;">XML</ulink>-structured response format
- -- <ulink url="&url.xslt;">XSLT</ulink> is used to normalize and extract
- data from retrieval records for display and analysis. It can be used
- against any server which supports the
- <ulink url="&url.z39.50;">Z39.50</ulink>, <ulink url="&url.sru;">SRU/SRW</ulink>
- or <ulink url="&url.solr;">SOLR</ulink> protocol. Proprietary
- backend modules can function as connectors between these standard
- protocols and any non-standard API, including web-site scraping, to
- support a large number of other protocols.
- </para>
- <para>
- Additional functionality such as
- user management and attractive displays are expected to be implemented by
- applications that use Pazpar2. Pazpar2 itself is user-interface independent.
- Its functionality is exposed through a simple XML-based web-service API,
- designed to be easy to use from an Ajax-enabled browser, Flash
- animation, Java applet, etc., or from a higher-level server-side language
- like PHP, Perl or Java. Because session information can be shared between
- browser-based logic and server-side scripting, there is tremendous
- flexibility in how you implement application-specific logic on top
- of Pazpar2.
- </para>
- <para>
- Once you launch a search in Pazpar2, the operation continues behind the
- scenes. Pazpar2 connects to servers, carries out searches, and
- retrieves, deduplicates, and stores results internally. Your application
- code may periodically inquire about the status of an ongoing operation,
- and ask to see records or result set facets. Results become
- available immediately, and it is easy to build end-user interfaces than
- feel extremely responsive, even when searching more than 100 servers
- concurrently.
- </para>
- <para>
- Pazpar2 is designed to be highly configurable. Incoming records are
- normalized to XML/UTF-8, and then further normalized using XSLT to a
- simple internal representation that is suitable for analysis. By
- providing XSLT stylesheets for different kinds of result records, you
- can configure Pazpar2 to work against different kinds of information
- retrieval servers. Finally, metadata is extracted in a configurable
- way from this internal record, to support display, merging, ranking,
- result set facets, and sorting. Pazpar2 is not bound to a specific model
- of metadata, such as DublinCore or MARC: by providing the right
- configuration, it can work with any combination of different kinds of data in
- support of many different applications.
- </para>
- <para>
- Pazpar2 is designed to be efficient and scalable. You can set it up to
- search several hundred targets in parallel, or you can use it to support
- hundreds of concurrent users. It is implemented with the same attention
- to performance and economy that we use in our indexing engines, so that
- you can focus on building your application without worrying about the
- details of metasearch logic. You can devote all of your attention to
- usability and let Pazpar2 do what it does best -- metasearch.
- </para>
- <para>
- Pazpar2 is our attempt to re-think the traditional paradigms for
- implementing and deploying metasearch logic, with an uncompromising
- approach to performance, and attempting to make maximum use of the
- capabilities of modern browsers. The demo user interface that
- accompanies the distribution is but one example. If you think of new
- ways of using Pazpar2, we hope you'll share them with us, and if we
- can provide assistance with regards to training, design, programming,
- integration with different backends, hosting, or support, please don't
- hesitate to contact us. If you'd like to see functionality in Pazpar2
- that is not there today, please don't hesitate to contact us. It may
- already be in our development pipeline, or there might be a
- possibility for you to help out by sponsoring development time or
- code. Either way, get in touch and we will give you straight answers.
- </para>
- <para>
- Enjoy!
- </para>
- <para>
- Pazpar2 is covered by the GNU General Public License (GPL) version 2.
- See <xref linkend="license"/> for further information.
- </para>
+ <title>What Pazpar2 is</title>
+ <para>
+ Pazpar2 is a stand-alone metasearch engine with a web-service API, designed
+ to be used either from a browser-based client (JavaScript, Flash,
+ Java applet,
+ etc.), from server-side code, or any combination of the two.
+ Pazpar2 is a highly optimized client designed to
+ search many resources in parallel. It implements record merging,
+ relevance-ranking and sorting by arbitrary data content, and facet
+ analysis for browsing purposes. It is designed to be data-model
+ independent, and is capable of working with MARC, DublinCore, or any
+ other <ulink url="&url.xml;">XML</ulink>-structured response format
+ -- <ulink url="&url.xslt;">XSLT</ulink> is used to normalize and extract
+ data from retrieval records for display and analysis. It can be used
+ against any server which supports the
+ <ulink url="&url.z39.50;">Z39.50</ulink>, <ulink url="&url.sru;">SRU/SRW</ulink>
+ or <ulink url="&url.solr;">SOLR</ulink> protocol. Proprietary
+ backend modules can function as connectors between these standard
+ protocols and any non-standard API, including web-site scraping, to
+ support a large number of other protocols.
+ </para>
+ <para>
+ Additional functionality such as
+ user management and attractive displays are expected to be implemented by
+ applications that use Pazpar2. Pazpar2 itself is user-interface independent.
+ Its functionality is exposed through a simple XML-based web-service API,
+ designed to be easy to use from an Ajax-enabled browser, Flash
+ animation, Java applet, etc., or from a higher-level server-side language
+ like PHP, Perl or Java. Because session information can be shared between
+ browser-based logic and server-side scripting, there is tremendous
+ flexibility in how you implement application-specific logic on top
+ of Pazpar2.
+ </para>
+ <para>
+ Once you launch a search in Pazpar2, the operation continues behind the
+ scenes. Pazpar2 connects to servers, carries out searches, and
+ retrieves, deduplicates, and stores results internally. Your application
+ code may periodically inquire about the status of an ongoing operation,
+ and ask to see records or result set facets. Results become
+ available immediately, and it is easy to build end-user interfaces than
+ feel extremely responsive, even when searching more than 100 servers
+ concurrently.
+ </para>
+ <para>
+ Pazpar2 is designed to be highly configurable. Incoming records are
+ normalized to XML/UTF-8, and then further normalized using XSLT to a
+ simple internal representation that is suitable for analysis. By
+ providing XSLT stylesheets for different kinds of result records, you
+ can configure Pazpar2 to work against different kinds of information
+ retrieval servers. Finally, metadata is extracted in a configurable
+ way from this internal record, to support display, merging, ranking,
+ result set facets, and sorting. Pazpar2 is not bound to a specific model
+ of metadata, such as DublinCore or MARC: by providing the right
+ configuration, it can work with any combination of different kinds of data
+ in support of many different applications.
+ </para>
+ <para>
+ Pazpar2 is designed to be efficient and scalable. You can set it up to
+ search several hundred targets in parallel, or you can use it to support
+ hundreds of concurrent users. It is implemented with the same attention
+ to performance and economy that we use in our indexing engines, so that
+ you can focus on building your application without worrying about the
+ details of metasearch logic. You can devote all of your attention to
+ usability and let Pazpar2 do what it does best -- metasearch.
+ </para>
+ <para>
+ Pazpar2 is our attempt to re-think the traditional paradigms for
+ implementing and deploying metasearch logic, with an uncompromising
+ approach to performance, and attempting to make maximum use of the
+ capabilities of modern browsers. The demo user interface that
+ accompanies the distribution is but one example. If you think of new
+ ways of using Pazpar2, we hope you'll share them with us, and if we
+ can provide assistance with regards to training, design, programming,
+ integration with different backends, hosting, or support, please don't
+ hesitate to contact us. If you'd like to see functionality in Pazpar2
+ that is not there today, please don't hesitate to contact us. It may
+ already be in our development pipeline, or there might be a
+ possibility for you to help out by sponsoring development time or
+ code. Either way, get in touch and we will give you straight answers.
+ </para>
+ <para>
+ Enjoy!
+ </para>
+ <para>
+ Pazpar2 is covered by the GNU General Public License (GPL) version 2.
+ See <xref linkend="license"/> for further information.
+ </para>
</section>
<section id="connectors">
- <title>Connectors to non-standard databases</title>
- <para>
- If you wish to connect to commercial or other databases which do not
- support open standards, please contact Index Data on
- <email>info@indexdata.com</email>. We have a
- proprietary framework for building connectors that enable Pazpar2
- to access
- thousands of online databases, in addition to the vast number of catalogs
- and online services that support the Z39.50/SRU/SRW/SOLR protocols.
- </para>
+ <title>Connectors to non-standard databases</title>
+ <para>
+ If you wish to connect to commercial or other databases which do not
+ support open standards, please contact Index Data on
+ <email>info@indexdata.com</email>. We have a
+ proprietary framework for building connectors that enable Pazpar2
+ to access
+ thousands of online databases, in addition to the vast number of catalogs
+ and online services that support the Z39.50/SRU/SRW/SOLR protocols.
+ </para>
</section>
-
+
<section id="name">
<title>A note on the name Pazpar2</title>
<para>
Pazpar2 depends on the following tools/libraries:
<variablelist>
<varlistentry><term><ulink url="&url.yaz;">YAZ</ulink></term>
- <listitem>
- <para>
- The popular Z39.50 toolkit for the C language.
- YAZ <emphasis>must</emphasis> be compiled with Libxml2/Libxslt support.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The popular Z39.50 toolkit for the C language.
+ YAZ <emphasis>must</emphasis> be compiled with Libxml2/Libxslt support.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry><term><ulink url="&url.icu;">International
- Components for Unicode (ICU)</ulink></term>
- <listitem>
- <para>
- ICU provides Unicode support for non-English languages with
- character sets outside the range of 7bit ASCII, like
- Greek, Russian, German and French. Pazpar2 uses the ICU
- Unicode character conversions, Unicode normalization, case
- folding and other fundamental operations needed in
- tokenization, normalization and ranking of records.
- </para>
- <para>
- Compiling, linking, and usage of the ICU libraries is optional,
- but strongly recommended for usage in an international
- environment.
- </para>
- </listitem>
+ Components for Unicode (ICU)</ulink></term>
+ <listitem>
+ <para>
+ ICU provides Unicode support for non-English languages with
+ character sets outside the range of 7bit ASCII, like
+ Greek, Russian, German and French. Pazpar2 uses the ICU
+ Unicode character conversions, Unicode normalization, case
+ folding and other fundamental operations needed in
+ tokenization, normalization and ranking of records.
+ </para>
+ <para>
+ Compiling, linking, and usage of the ICU libraries is optional,
+ but strongly recommended for usage in an international
+ environment.
+ </para>
+ </listitem>
</varlistentry>
</variablelist>
</para>
changed with configure option <option>--prefix</option>.
</para>
</section>
-
+
<section id="installation.win32">
- <title>Installation from source on Windows</title>
- <para>
- Pazpar2 can be built for Windows using
- <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink>.
- The support files for building YAZ on Windows are located in the
- <filename>win</filename> directory. The compilation is performed
- using the <filename>win/makefile</filename> which is to be
- processed by the NMAKE utility part of Visual Studio.
- </para>
- <para>
- Ensure that the development libraries and header files are
- available on your system before compiling Pazpar2. For installation
- of YAZ, refer to
- the Installation chapter of the YAZ manual at
- <ulink url="&url.yaz.install;"/>.
- It is easiest if YAZ and Pazpar2 are unpacked in the same
- directory (side-by-side).
- </para>
- <para>
- The compilation is tuned by editing the makefile of Pazpar2.
- The process is similar to YAZ. Adjust the various directories
- <literal>YAZ_DIR</literal>, <literal>ZLIB_DIR</literal>, etc.,
- as required.
- </para>
- <para>
- Compile Pazpar2 by invoking <application>nmake</application> in
- the <filename>win</filename> directory.
- The resulting binaries of the build process are located in the
- <filename>bin</filename> of the Pazpar2 source
- tree - including the <filename>pazpar2.exe</filename> and necessary DLLs.
- </para>
- <para>
- The Windows version of Pazpar2 is a console application. It may
- be installed as a Windows Service by adding option
- <literal>-install</literal> for the pazpar2 program. This will
- register Pazpar2 as a service and use the other options provided
- in the same invocation. For example:
- <screen>
- cd \MyPazpar2\etc
- ..\bin\pazpar2 -install -f pazpar2.cfg -l pazpar2.log
- </screen>
- The Pazpar2 service may now be controlled via the Service Control
- Panel. It may be unregistered by passing the <literal>-remove</literal>
- option. Example:
- <screen>
- cd \MyPazpar2\etc
- ..\bin\pazpar2 -remove
- </screen>
- </para>
+ <title>Installation from source on Windows</title>
+ <para>
+ Pazpar2 can be built for Windows using
+ <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink>.
+ The support files for building YAZ on Windows are located in the
+ <filename>win</filename> directory. The compilation is performed
+ using the <filename>win/makefile</filename> which is to be
+ processed by the NMAKE utility part of Visual Studio.
+ </para>
+ <para>
+ Ensure that the development libraries and header files are
+ available on your system before compiling Pazpar2. For installation
+ of YAZ, refer to
+ the Installation chapter of the YAZ manual at
+ <ulink url="&url.yaz.install;"/>.
+ It is easiest if YAZ and Pazpar2 are unpacked in the same
+ directory (side-by-side).
+ </para>
+ <para>
+ The compilation is tuned by editing the makefile of Pazpar2.
+ The process is similar to YAZ. Adjust the various directories
+ <literal>YAZ_DIR</literal>, <literal>ZLIB_DIR</literal>, etc.,
+ as required.
+ </para>
+ <para>
+ Compile Pazpar2 by invoking <application>nmake</application> in
+ the <filename>win</filename> directory.
+ The resulting binaries of the build process are located in the
+ <filename>bin</filename> of the Pazpar2 source
+ tree - including the <filename>pazpar2.exe</filename> and necessary DLLs.
+ </para>
+ <para>
+ The Windows version of Pazpar2 is a console application. It may
+ be installed as a Windows Service by adding option
+ <literal>-install</literal> for the pazpar2 program. This will
+ register Pazpar2 as a service and use the other options provided
+ in the same invocation. For example:
+ <screen>
+ cd \MyPazpar2\etc
+ ..\bin\pazpar2 -install -f pazpar2.cfg -l pazpar2.log
+ </screen>
+ The Pazpar2 service may now be controlled via the Service Control
+ Panel. It may be unregistered by passing the <literal>-remove</literal>
+ option. Example:
+ <screen>
+ cd \MyPazpar2\etc
+ ..\bin\pazpar2 -remove
+ </screen>
+ </para>
</section>
-
+
<section id="installation.test1">
<title>Installation of test interfaces</title>
<para>
</section>
<section id="installation.debian">
- <title>Installation on Debian or Ubuntu GNU/Linux</title>
+ <title>Installation on Debian GNU/Linux and Ubuntu</title>
<para>
Index Data provides Debian and Ubuntu packages for Pazpar2.
As of February 2010, these
<ulink url="&url.pazpar2.download.ubuntu;"/>.
</para>
</section>
-
+
<section id="installation.apache2proxy">
<title>Apache 2 Proxy</title>
<para>
Apache 2 has a
- <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
+ <ulink
+ url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
proxy module
- </ulink> which allows Pazpar2 to become a backend to an Apache 2
+ </ulink>
+ which allows Pazpar2 to become a backend to an Apache 2
based web service. The Apache 2 proxy must operate in the
<emphasis>Reverse</emphasis> Proxy mode.
</para>
sudo a2enmod proxy_http proxy_balancer
</screen>
</para>
-
+
<para>
Traditionally Pazpar2 interprets URL paths with suffix
<literal>/search.pz2</literal>.
The
- <ulink
- url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass"
- >ProxyPass</ulink> directive of Apache must be used to map a URL path
+ <ulink
+ url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass">
+ ProxyPass
+ </ulink>
+ directive of Apache must be used to map a URL path
the the Pazpar2 server (listening port).
</para>
</para>
</example>
</section>
-
+
</chapter>
-
+
<chapter id="using">
<title>Using Pazpar2</title>
<para>
This chapter provides a general introduction to the use and
deployment of Pazpar2.
</para>
-
+
<section id="architecture">
<title>Pazpar2 and your systems architecture</title>
<para>
with the server from which the enclosing HTML page or object
originated, Pazpar2 is designed so that it can act as a transparent
proxy in front of an existing webserver (see <xref
- linkend="pazpar2_conf"/> for details).
+ linkend="pazpar2_conf"/> for details).
In this mode, all regular
HTTP requests are transparently passed through to your webserver,
while Pazpar2 only intercepts search-related webservice requests.
<!-- ... and so on -->
</record>
]]></screen>
-
+
As you can see, there isn't much to it. There are really only a few
important elements to this file.
</para>
-
+
<para>
Elements should belong to the namespace
<literal>http://www.indexdata.com/pazpar2/1.0</literal>.
The webservice API of Pazpar2 is described in detail in <xref
linkend="pazpar2_protocol"/>.
</para>
-
+
<para>
In brief, you use the 'init' command to create a session, a
temporary workspace which carries information about the current
no effort. Resources that use non-standard record formats will
require a bit of XSLT work, but that's all.
</para>
-
+
<para>
- But what about resources that don't support Z39.50 at all? Some resources might
- support OpenSearch, private, XML/HTTP-based protocols, or something
- else entirely. Some databases exist only as web user interfaces and
+ But what about resources that don't support Z39.50 at all?
+ Some resources might support OpenSearch, private, XML/HTTP-based
+ protocols, or something else entirely.
+ Some databases exist only as web user interfaces and
will require screen-scraping. Still others exist only as static
files, or perhaps as databases supporting the OAI-PMH protocol.
There is hope! Read on.
work with database vendors to support standards, so you don't have
to worry about programming against non-standard services. We also
provide tools (see <ulink
- url="http://www.indexdata.com/simpleserver">SimpleServer</ulink>)
+ url="http://www.indexdata.com/simpleserver">SimpleServer</ulink>)
which make it comparatively easy to build gateways against servers
with non-standard behavior. Again, we encourage you to share any
work you do in this direction.
</para>
-
+
<para>
But the bottom line is that working with non-standard resources in
metasearching is really, really hard. If you want to build a
<section id="load_balancing">
<title>Load balancing</title>
<para>
- Just like any web server, Pazpar2, can be load balanced by a standard hardware or software load balancer as long as the session stickiness is ensured. If you are already running the Apache2 web server in front of Pazpar2 and use the apache mod_proxy module to 'relay' client requests to Pazpar2, this set up can be easily extended to include load balancing capabilites. To do so you need to enable the <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html">
- mod_proxy_balancer
- </ulink> module in your Apache2 installation.
+ Just like any web server, Pazpar2, can be load balanced by a standard
+ hardware or software load balancer as long as the session stickiness
+ is ensured. If you are already running the Apache2 web server in front
+ of Pazpar2 and use the apache mod_proxy module to 'relay' client
+ requests to Pazpar2, this set up can be easily extended to include
+ load balancing capabilites.
+ To do so you need to enable the
+ <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html">
+ mod_proxy_balance
+ </ulink>
+ module in your Apache2 installation.
</para>
<para>
</para>
<para>
- The mod_proxy_balancer can pass all 'sessionsticky' requests to the same backend worker as long as the requests are marked with the originating worker's ID (called 'route'). If the Pazpar2 serverID is configured (by setting an 'id' attribute on the 'server' element in the Pazpar2 configuration file) Pazpar2 will append it to the 'session' element returned during the 'init' in a mod_proxy_balancer compatible manner. Since the 'session' is then re-sent by the client (for all pazpar2 request besides 'init'), the balancer can use the marker to pass the request to the right route. To do so the balancer needs to be configured to inspect the 'session' parameter.
+ The mod_proxy_balancer can pass all 'sessionsticky' requests to the
+ same backend worker as long as the requests are marked with the
+ originating worker's ID (called 'route'). If the Pazpar2 serverID is
+ configured (by setting an 'id' attribute on the 'server' element in
+ the Pazpar2 configuration file) Pazpar2 will append it to the
+ 'session' element returned during the 'init' in a mod_proxy_balancer
+ compatible manner.
+ Since the 'session' is then re-sent by the client (for all pazpar2
+ request besides 'init'), the balancer can use the marker to pass
+ the request to the right route. To do so the balancer needs to be
+ configured to inspect the 'session' parameter.
</para>
<example id="load_balancing.example">
<title>Apache 2 load balancing configuration</title>
<para>
- Having 4 Pazpar2 instances running on the same host, port range of 8004-8007 and serverIDs of: pz1, pz2, pz3 and pz4 respectively we could use the following Apache 2 configuration to expose a single pazpar2 'endpoint' on a standard (<filename>/pazpar2/search.pz2</filename>) location:
-
+ Having 4 Pazpar2 instances running on the same host, port range of
+ 8004-8007 and serverIDs of: pz1, pz2, pz3 and pz4 respectively we
+ could use the following Apache 2 configuration to expose a single
+ pazpar2 'endpoint' on a standard
+ (<filename>/pazpar2/search.pz2</filename>) location:
+
<screen><![CDATA[
<Proxy *>
AddDefaultCharset off
# route is resent in the 'session' param which has the form:
# 'sessid.serverid', understandable by the mod_proxy_load_balancer
# this is not going to work if the client tampers with the 'session' param
- ProxyPass /pazpar2/search.pz2 balancer://pz2cluster lbmethod=byrequests stickysession=session nofailover=On]]></screen>
-
- The 'ProxyPass' line sets up a reverse proxy for request ‘/pazpar2/search.pz2’ and delegates all requests to the load balancer (virtual worker) with name ‘pz2cluster’. Sticky sessions are enabled and implemented using the ‘session’ parameter. The ‘Proxy’ section lists all the servers (real workers) which the load balancer can use.
- </para>
-
- </example>
-
+ ProxyPass /pazpar2/search.pz2 balancer://pz2cluster lbmethod=byrequests stickysession=session nofailover=On
+ ]]></screen>
+
+ The 'ProxyPass' line sets up a reverse proxy for request
+ ‘/pazpar2/search.pz2’ and delegates all requests to the load balancer
+ (virtual worker) with name ‘pz2cluster’.
+ Sticky sessions are enabled and implemented using the ‘session’ parameter.
+ The ‘Proxy’ section lists all the servers (real workers) which the
+ load balancer can use.
+ </para>
+
+ </example>
+
</section>
-
+
</chapter> <!-- Using Pazpar2 -->
&manref;
</reference>
- <appendix id="license"><title>License</title>
-
- <para>
- Pazpar2,
- Copyright © ©right-year; Index Data.
- </para>
-
- <para>
- Pazpar2 is free software; you can redistribute it and/or modify it under
- the terms of the GNU General Public License as published by the Free
- Software Foundation; either version 2, or (at your option) any later
- version.
- </para>
-
- <para>
- Pazpar2 is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or
- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
- for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public License
- along with Pazpar2; see the file LICENSE. If not, write to the
- Free Software Foundation,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
- </para>
-
+ <appendix id="license">
+ <title>License</title>
+
+ <para>
+ Pazpar2,
+ Copyright © ©right-year; Index Data.
+ </para>
+
+ <para>
+ Pazpar2 is free software; you can redistribute it and/or modify it under
+ the terms of the GNU General Public License as published by the Free
+ Software Foundation; either version 2, or (at your option) any later
+ version.
+ </para>
+
+ <para>
+ Pazpar2 is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ for more details.
+ </para>
+
+ <para>
+ You should have received a copy of the GNU General Public License
+ along with Pazpar2; see the file LICENSE. If not, write to the
+ Free Software Foundation,
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ </para>
+
</appendix>
&gpl2;
</book>
- <!-- Keep this comment at the end of the file
- Local variables:
- mode: sgml
- sgml-omittag:t
- sgml-shorttag:t
- sgml-minimize-attributes:nil
- sgml-always-quote-attributes:t
- sgml-indent-step:1
- sgml-indent-data:t
- sgml-parent-document: nil
- sgml-local-catalogs: nil
- sgml-namecase-general:t
- End:
- -->
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: nxml
+nxml-child-indent: 1
+End:
+-->
</cmdsynopsis>
</refsynopsisdiv>
- <refsect1><title>DESCRIPTION</title>
- <para><command>pazpar2</command> is the Pazpar2 Metasearch daemon
+ <refsect1>
+ <title>DESCRIPTION</title>
+ <para>
+ <command>pazpar2</command> is the Pazpar2 Metasearch daemon
and server.
In normal operation it acts as a simple HTTP server which serves
the Pazpar2 protocol.
</para>
</refsect1>
- <refsect1><title>OPTIONS</title>
- <para></para>
+ <refsect1>
+ <title>OPTIONS</title>
<variablelist>
<varlistentry>
<varlistentry>
<term><option>-D</option></term>
<listitem>
- <para>Puts the Pazpar2 server in the background.</para>
+ <para>
+ Puts the Pazpar2 server in the background.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-install</option></term>
<listitem>
<para>
- This is an option which is only recognized on Windows. It installs
- Pazpar2 as a Windows Service.
+ This is an option which is only recognized on Windows. It installs
+ Pazpar2 as a Windows Service.
</para>
<note>
- <para>
- Pazpar2 only supports Windows Service options if Pazpar2 is
- linked against YAZ 3.0.29 or later.
- </para>
+ <para>
+ Pazpar2 only supports Windows Service options if Pazpar2 is
+ linked against YAZ 3.0.29 or later.
+ </para>
</note>
</listitem>
</varlistentry>
<term><option>-remove</option></term>
<listitem>
<para>
- This is an option which is only recognized on Windows. It removes
- a Pazpar2 - Windows Service.
+ This is an option which is only recognized on Windows. It removes
+ a Pazpar2 - Windows Service.
</para>
</listitem>
</varlistentry>
</refsect1>
- <refsect1><title>EXAMPLES</title>
+ <refsect1>
+ <title>EXAMPLES</title>
<para>The Debian package of pazpar2 starts the server with:
<screen>
pazpar2 -D -f /etc/pazpar2/pazpar2.cfg -l /var/log/pazpar2.log -p /var/run/pazpar2.pid -u nobody
</para>
</refsect1>
- <refsect1><title>FILES</title>
+ <refsect1>
+ <title>FILES</title>
<para><filename>/usr/sbin/pazpar2</filename>: pazpar2 daemon</para>
-
+
<para><filename>/usr/share/pazpar2</filename>: pazpar2 shared files</para>
-
+
<para><filename>/etc/pazpar2</filename>: pazpar2 config area</para>
</refsect1>
- <refsect1><title>SEE ALSO</title>
+ <refsect1>
+ <title>SEE ALSO</title>
<para>
Pazpar2 configuration:
<citerefentry>
</refentry>
-
<!-- Keep this comment at the end of the file
Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
+mode: nxml
+nxml-child-indent: 1
End:
-->
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>Pazpar2 conf</refentrytitle>
<manvolnum>5</manvolnum>
</cmdsynopsis>
</refsynopsisdiv>
- <refsect1><title>DESCRIPTION</title>
+ <refsect1>
+ <title>DESCRIPTION</title>
<para>
The Pazpar2 configuration file, together with any referenced XSLT files,
govern Pazpar2's behavior as a client, and control the normalization and
</para>
</refsect1>
- <refsect1><title>FORMAT</title>
+ <refsect1>
+ <title>FORMAT</title>
<para>
The configuration file is XML-structured. It must be well-formed XML. All
elements specific to Pazpar2 should belong to the namespace
information. The categories are described below.
</para>
- <refsect2 id="config-threads"><title>threads</title>
- <para>
- This section is optional and is supported for Pazpar2 version 1.3.1 and
- later . It is identified by element "<literal>threads</literal>" which
- may include one attribute "<literal>number</literal>" which specifies
- the number of worker-threads that the Pazpar2 instance is to use.
- A value of 0 (zero) disables worker-threads (all work is carried out
- in main thread).
- </para>
+ <refsect2 id="config-threads">
+ <title>threads</title>
+ <para>
+ This section is optional and is supported for Pazpar2 version 1.3.1 and
+ later . It is identified by element "<literal>threads</literal>" which
+ may include one attribute "<literal>number</literal>" which specifies
+ the number of worker-threads that the Pazpar2 instance is to use.
+ A value of 0 (zero) disables worker-threads (all work is carried out
+ in main thread).
+ </para>
</refsect2>
- <refsect2 id="config-server"><title>server</title>
+ <refsect2 id="config-server">
+ <title>server</title>
<para>
This section governs overall behavior of a server endpoint. It is identified
by the element "server" which takes an optional attribute, "id", which
identifies this particular Pazpar2 server. Any string value for "id"
may be given.
</para>
- <para>The data
+ <para>
+ The data
elements are described below. From Pazpar2 version 1.2 this is
a repeatable element.
</para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>relevance / sort / mergekey / facet</term>
<listitem>
</para>
<variablelist> <!-- Level 2 -->
- <varlistentry><term>metadata</term>
+ <varlistentry>
+ <term>metadata</term>
<listitem>
<para>
One of these elements is required for every data element in
the internal representation of the record (see
<xref linkend="data_model"/>. It governs
- subsequent processing as pertains to sorting, relevance
- ranking, merging, and display of data elements. It supports
- the following attributes:
+ subsequent processing as pertains to sorting, relevance
+ ranking, merging, and display of data elements. It supports
+ the following attributes:
</para>
<variablelist> <!-- level 3 -->
- <varlistentry><term>name</term>
+ <varlistentry>
+ <term>name</term>
<listitem>
<para>
This is the name of the data element. It is matched
</listitem>
</varlistentry>
- <varlistentry><term>type</term>
+ <varlistentry>
+ <term>type</term>
<listitem>
<para>
The type of data element. This value governs any
</listitem>
</varlistentry>
- <varlistentry><term>brief</term>
+ <varlistentry>
+ <term>brief</term>
<listitem>
<para>
If this is set to 'yes', then the data element is
</listitem>
</varlistentry>
- <varlistentry><term>sortkey</term>
+ <varlistentry>
+ <term>sortkey</term>
<listitem>
<para>
Specifies that this data element is to be used for
</listitem>
</varlistentry>
- <varlistentry><term>rank</term>
+ <varlistentry>
+ <term>rank</term>
<listitem>
<para>
Specifies that this element is to be used to
</listitem>
</varlistentry>
- <varlistentry><term>termlist</term>
+ <varlistentry>
+ <term>termlist</term>
<listitem>
<para>
Specifies that this element is to be used as a
</listitem>
</varlistentry>
- <varlistentry><term>merge</term>
+ <varlistentry>
+ <term>merge</term>
<listitem>
<para>
This governs whether, and how elements are extracted
</para>
</listitem>
</varlistentry>
-
- <varlistentry><term>mergekey</term>
+
+ <varlistentry>
+ <term>mergekey</term>
<listitem>
<para>
If set to '<literal>required</literal>', the value of this
</para>
</listitem>
</varlistentry>
-
- <varlistentry><term>setting</term>
+
+ <varlistentry>
+ <term>setting</term>
<listitem>
<para>
This attribute allows you to make use of static database
in order from top to bottom.
</para>
<variablelist> <!-- Level 2 -->
- <varlistentry><term>casemap</term>
+ <varlistentry>
+ <term>casemap</term>
<listitem>
<para>
The attribute 'rule' defines the direction of the
</para>
</listitem>
</varlistentry>
- <varlistentry><term>transform</term>
+ <varlistentry>
+ <term>transform</term>
<listitem>
<para>
Normalization and transformation of tokens follows
possible values we refer to the extensive ICU
documentation found at the
<ulink url="&url.icu.transform;">ICU
- transformation</ulink> home page. Set filtering
+ transformation</ulink> home page. Set filtering
principles are explained at the
<ulink url="&url.icu.unicode.set;">ICU set and
- filtering</ulink> page.
+ filtering</ulink> page.
</para>
</listitem>
</varlistentry>
- <varlistentry><term>tokenize</term>
+ <varlistentry>
+ <term>tokenize</term>
<listitem>
<para>
Tokenization is the only rule in the ICU chain
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>settings</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
</variablelist> <!-- Data elements in service directive -->
</listitem>
</varlistentry>
-
</variablelist> <!-- Data elements in server directive -->
</refsect2>
-
</refsect1>
-
- <refsect1><title>EXAMPLE</title>
- <para>Below is a working example configuration:
- <screen><![CDATA[
- <?xml version="1.0" encoding="UTF-8"?>
- <pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
-
- <threads number="10"/>
- <server>
- <listen port="9004"/>
- <service>
- <metadata name="title" brief="yes" sortkey="skiparticle"
+
+ <refsect1>
+ <title>EXAMPLE</title>
+ <para>
+ Below is a working example configuration:
+ </para>
+ <screen>
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
+
+ <threads number="10"/>
+ <server>
+ <listen port="9004"/>
+ <service>
+ <metadata name="title" brief="yes" sortkey="skiparticle"
merge="longest" rank="6"/>
- <metadata name="isbn" merge="unique"/>
- <metadata name="date" brief="yes" sortkey="numeric"
+ <metadata name="isbn" merge="unique"/>
+ <metadata name="date" brief="yes" sortkey="numeric"
type="year" merge="range" termlist="yes"/>
- <metadata name="author" brief="yes" termlist="yes"
+ <metadata name="author" brief="yes" termlist="yes"
merge="longest" rank="2"/>
- <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
- <metadata name="url" merge="unique"/>
- <relevance>
- <icu_chain id="relevance" locale="el">
- <transform rule="[:Control:] Any-Remove"/>
- <tokenize rule="l"/>
- <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
- <casemap rule="l"/>
- </icu_chain>
- </relevance>
- <settings src="mysettings"/>
- <timeout session="60"/>
- <service>
- </server>
- </pazpar2>
- ]]></screen>
- </para>
+ <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
+ <metadata name="url" merge="unique"/>
+ <relevance>
+ <icu_chain id="relevance" locale="el">
+ <transform rule="[:Control:] Any-Remove"/>
+ <tokenize rule="l"/>
+ <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
+ <casemap rule="l"/>
+ </icu_chain>
+ </relevance>
+ <settings src="mysettings"/>
+ <timeout session="60"/>
+ <service>
+ </server>
+</pazpar2>
+ ]]>
+ </screen>
</refsect1>
- <refsect1 id="config-include"><title>INCLUDE FACILITY</title>
+ <refsect1 id="config-include">
+ <title>INCLUDE FACILITY</title>
<para>
The XML configuration may be partitioned into multiple files by using
the <literal>include</literal> element which takes a single attribute,
<literal>src</literal>. The of the <literal>src</literal> attribute is
regular Shell like glob-pattern. For example,
<screen><![CDATA[
- <include src="/etc/pazpar2/conf.d/*.xml"/>
- ]]></screen>
+ <include src="/etc/pazpar2/conf.d/*.xml"/>
+ ]]></screen>
</para>
<para>
The include facility requires Pazpar2 version 1.2.
</para>
</refsect1>
- <refsect1 id="target_settings"><title>TARGET SETTINGS</title>
+ <refsect1 id="target_settings">
+ <title>TARGET SETTINGS</title>
<para>
Pazpar2 features a cunning scheme by which you can associate various
kinds of attributes, or settings with search targets. This can be done
on a per-session basis. This allows the client to override specific CCL fields
for searching, etc., to meet the needs of a session or user.
</para>
-
+
<para>
Finally, as an extreme case of this, the webservice client can
introduce entirely new targets, on the fly, as part of the
long as the webservice client is prepared to supply the necessary
information at the beginning of every session.
</para>
-
+
<note>
<para>
The following discussion of practical issues related to session and settings
technology. It would apply equally well to many other kinds of browser-based logic.
</para>
</note>
-
+
<para>
Typically, a Javascript client is not allowed to directly alter the parameters
of a session. There are two reasons for this. One has to do with access
webserver. Typically, this can be handled during the session initialization,
as follows:
</para>
-
+
<para>
Step 1: The Javascript client loads, and asks the webserver for a new Pazpar2
session ID. This can be done using a Javascript call, for instance. Note that
it is possible to submit Ajax HTTPXmlRequest calls either to Pazpar2 or to the
webserver that Pazpar2 is proxying for. See (XXX Insert link to Pazpar2 protocol).
- </para>
-
+ </para>
+
<para>
Step 2: Code on the webserver authenticates the user, by database lookup,
LDAP access, NCIP, etc. Determines which resources the user has access to,
and any user-specific parameters that are to be applied during this session.
</para>
-
+
<para>
Step 3: The webserver initializes a new Pazpar2 settings, and sets user-specific
parameters as necessary, using the init webservice command. A new session ID is
returned.
</para>
-
+
<para>
Step 4: The webserver returns this session ID to the Javascript client, which then
uses the session ID to submit searches, show results, etc.
</para>
-
+
<para>
Step 5: When the Javascript client ceases to use the session, Pazpar2 destroys
any session-specific information.
</para>
- <refsect2><title>SETTINGS FILE FORMAT</title>
+ <refsect2>
+ <title>SETTINGS FILE FORMAT</title>
<para>
Each file contains a root element named <settings>. It may
contain one or more <set> elements. The settings and set
specify (directly, or inherited from the parent node) at least a
target, name, and value.
</para>
-
+
<variablelist>
<varlistentry>
<term>target</term>
</listitem>
</varlistentry>
</variablelist>
-
+
<para>
By setting defaults for target, name, or value in the root
settings node, you can use the settings files in many different
many databases with a given category or class that makes sense
within your application.
</para>
-
+
<para>
The following examples illustrate uses of the settings system to
associate settings with targets to meet different requirements.
</para>
-
+
<para>
The example below associates a set of default values that can be
used across many targets. Note the wildcard for targets.
This associates the given settings with all targets for which no
other information is provided.
<screen><![CDATA[
-<settings target="*">
+ <settings target="*">
- <!-- This file introduces default settings for pazpar2 -->
+ <!-- This file introduces default settings for pazpar2 -->
- <!-- mapping for unqualified search -->
- <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
+ <!-- mapping for unqualified search -->
+ <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
- <!-- field-specific mappings -->
- <set name="pz:cclmap:ti" value="u=4 s=al"/>
- <set name="pz:cclmap:su" value="u=21 s=al"/>
- <set name="pz:cclmap:isbn" value="u=7"/>
- <set name="pz:cclmap:issn" value="u=8"/>
- <set name="pz:cclmap:date" value="u=30 r=r"/>
-q
- <set name="pz:limitmap:title" value="rpn:@attr 1=4 @attr 6=3"/>
- <set name="pz:limitmap:date" value="ccl:date"/>
+ <!-- field-specific mappings -->
+ <set name="pz:cclmap:ti" value="u=4 s=al"/>
+ <set name="pz:cclmap:su" value="u=21 s=al"/>
+ <set name="pz:cclmap:isbn" value="u=7"/>
+ <set name="pz:cclmap:issn" value="u=8"/>
+ <set name="pz:cclmap:date" value="u=30 r=r"/>
+
+ <set name="pz:limitmap:title" value="rpn:@attr 1=4 @attr 6=3"/>
+ <set name="pz:limitmap:date" value="ccl:date"/>
- <!-- Retrieval settings -->
+ <!-- Retrieval settings -->
- <set name="pz:requestsyntax" value="marc21"/>
- <set name="pz:elements" value="F"/>
+ <set name="pz:requestsyntax" value="marc21"/>
+ <set name="pz:elements" value="F"/>
- <!-- Query encoding -->
- <set name="pz:queryencoding" value="iso-8859-1"/>
+ <!-- Query encoding -->
+ <set name="pz:queryencoding" value="iso-8859-1"/>
- <!-- Result normalization settings -->
+ <!-- Result normalization settings -->
- <set name="pz:nativesyntax" value="iso2709"/>
- <set name="pz:xslt" value="../etc/marc21.xsl"/>
+ <set name="pz:nativesyntax" value="iso2709"/>
+ <set name="pz:xslt" value="../etc/marc21.xsl"/>
-</settings>
+ </settings>
- ]]></screen>
+ ]]></screen>
</para>
-
+
<para>
The next example shows certain settings overridden for one target,
one which returns XML records containing DublinCore elements, and
which furthermore requires a username/password.
<screen><![CDATA[
-<settings target="funkytarget.com:210/db1">
- <set name="pz:requestsyntax" value="xml"/>
- <set name="pz:nativesyntax" value="xml"/>
- <set name="pz:xslt" value="../etc/dublincore.xsl"/>
+ <settings target="funkytarget.com:210/db1">
+ <set name="pz:requestsyntax" value="xml"/>
+ <set name="pz:nativesyntax" value="xml"/>
+ <set name="pz:xslt" value="../etc/dublincore.xsl"/>
- <set name="pz:authentication" value="myuser/password"/>
-</settings>
- ]]></screen>
+ <set name="pz:authentication" value="myuser/password"/>
+ </settings>
+ ]]></screen>
</para>
-
+
<para>
The following example associates a specific name/value combination
with a number of targets. The targets below are access-restricted,
and can only be used by users with special credentials.
<screen><![CDATA[
-<settings name="pz:allow" value="0">
- <set target="funkytarget.com:210/*"/>
- <set target="commercial.com:2100/expensiveDb"/>
-</settings>
- ]]></screen>
+ <settings name="pz:allow" value="0">
+ <set target="funkytarget.com:210/*"/>
+ <set target="commercial.com:2100/expensiveDb"/>
+ </settings>
+ ]]></screen>
</para>
-
+
</refsect2>
-
- <refsect2><title>RESERVED SETTING NAMES</title>
+
+ <refsect2>
+ <title>RESERVED SETTING NAMES</title>
<para>
The following setting names are reserved by Pazpar2 to control the
behavior of the client function.
<term>pz:queryencoding</term>
<listitem>
<para>
- The encoding of the search terms that a target accepts. Most
- targets do not honor UTF-8 in which case this needs to be specified.
- Each term in a query will be converted if this setting is given.
+ The encoding of the search terms that a target accepts. Most
+ targets do not honor UTF-8 in which case this needs to be specified.
+ Each term in a query will be converted if this setting is given.
</para>
</listitem>
</varlistentry>
performance with the alternate "MARC map" format. Provide the
path of a file with extension ".mmap" containing on each line:
<programlisting>
- <field> <subfield> <metadata element></programlisting>
+ <field> <subfield> <metadata element></programlisting>
For example:
<programlisting>
- 245 a title
- 500 $ description
- 773 * citation</programlisting>
+ 245 a title
+ 500 $ description
+ 773 * citation
+ </programlisting>
To map the field value specify a subfield of '$'. To store a
concatenation of all subfields, specify a subfield of '*'.
</para>
<listitem>
<para>
Allows or denies access to the resources it is applied to. Possible
- values are '0' and '1'. The default is '1' (allow access to this resource).
- See the manual section on authorization and authentication for discussion
- about how to use this setting.
+ values are '0' and '1'.
+ The default is '1' (allow access to this resource).
+ See the manual section on authorization and authentication for
+ discussion about how to use this setting.
</para>
</listitem>
</varlistentry>
the protocol.
</para>
<para>
- A value of 'solr' anables SOLR client support. This is supported
- for Pazpar version 1.5.0 and later.
+ A value of 'solr' anables SOLR client support. This is supported
+ for Pazpar version 1.5.0 and later.
</para>
</listitem>
</varlistentry>
will be ignored. The filter takes the form name, name~value, or name=value, which
will include only records with metadata element (name) that has the
substring (~value) given, or matches exactly (=value). If value is omitted all records
- with the named
+ with the named
metadata element present will be included.
</para>
</listitem>
field on the target.
</para>
<note>
- <para>
- At this point only SOLR targets have been tested with this
- facility.
- </para>
+ <para>
+ At this point only SOLR targets have been tested with this
+ facility.
+ </para>
</note>
</listitem>
</varlistentry>
<term>pz:limitmap:<replaceable>name</replaceable></term>
<listitem>
<para>
- Specifies attributes for limiting a search to a field - using
- the limit parameter for search. In some cases the mapping of
- a field to a value is identical to an existing cclmap field; in
- other cases the field must be specified in a different way - for
- example to match a complete field (rather than parts of a subfield).
+ Specifies attributes for limiting a search to a field - using
+ the limit parameter for search. In some cases the mapping of
+ a field to a value is identical to an existing cclmap field; in
+ other cases the field must be specified in a different way - for
+ example to match a complete field (rather than parts of a subfield).
</para>
<para>
- The value of limitmap may have one of two forms: referral to
- an exisiting CCL field or a raw PQF string. Leading string
- determines type; either <literal>ccl:</literal> for CCL field or
- <literal>rpn:</literal> for PQF/RPN.
+ The value of limitmap may have one of two forms: referral to
+ an exisiting CCL field or a raw PQF string. Leading string
+ determines type; either <literal>ccl:</literal> for CCL field or
+ <literal>rpn:</literal> for PQF/RPN.
</para>
- <note>
- <para>
- The limitmap facility is supported for Pazpar2 version 1.6.0.
- </para>
+ <note>
+ <para>
+ The limitmap facility is supported for Pazpar2 version 1.6.0.
+ </para>
</note>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
-
+
</refsect1>
- <refsect1><title>SEE ALSO</title>
+ <refsect1>
+ <title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pazpar2</refentrytitle>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
+mode: nxml
+nxml-child-indent: 1
End:
-->
<refpurpose>The webservice protocol of Pazpar2</refpurpose>
</refnamediv>
- <refsect1><title>DESCRIPTION</title>
+ <refsect1>
+ <title>DESCRIPTION</title>
<para>
Webservice requests are any that refer to filename "search.pz2". Arguments
are GET-style parameters. Argument 'command' is always required and specifies
request is forwarded to the HTTP server specified in the configuration
using the proxy setting.
This way, a regular webserver can host the user interface (itself dynamic
- or static HTML), and Ajax-style calls can be used from JS (or any other client-based
- scripting environment) to interact with the search logic in Pazpar2.
+ or static HTML), and Ajax-style calls can be used from JS (or any other
+ client-based scripting environment) to interact with the search logic
+ in Pazpar2.
</para>
<para>
Each command is described in sub sections to follow.
</para>
- <refsect2 id="command-init"><title>init</title>
+ <refsect2 id="command-init">
+ <title>init</title>
<para>
Initializes a session.
Returns session ID to be used in subsequent requests. If
</init>
]]></screen>
<para>
- The init command may take a number of setting parameters, similar to
- the 'settings' command described below. These settings are immediately
- applied to the new session. Other parameters for init are:
+ The init command may take a number of setting parameters, similar to
+ the 'settings' command described below. These settings are immediately
+ applied to the new session. Other parameters for init are:
<variablelist>
<varlistentry>
<term>clear</term>
</para>
</refsect2>
- <refsect2 id="command-ping"><title>ping</title>
+ <refsect2 id="command-ping">
+ <title>ping</title>
<para>
Keeps a session alive. An idle session will time out after one minute.
The ping command can be used to keep the session alive absent other
<para>
Example:
<screen><![CDATA[
- search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
+search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
]]></screen>
Response:
<screen><![CDATA[
<status>OK</status>
</settings>
]]></screen>
- </para>
-
+ </para>
+
</refsect2>
- <refsect2 id="command-search"><title>search</title>
+ <refsect2 id="command-search">
+ <title>search</title>
<para>
Launches a search, parameters:
-
+
<variablelist>
<varlistentry>
<term>session</term>
<listitem>
<para>
Session ID
- </para>
+ </para>
</listitem>
</varlistentry>
<term>block</term>
<listitem>
<para>
- If block is set to 1, the command will hang until there are records ready
- to display. Use this to show first records rapidly without
+ If block is set to 1, the command will hang until there are records
+ ready to display. Use this to show first records rapidly without
requiring rapid polling.
</para>
</listitem>
field first. A sort field may be followed by a colon followed by
the number '0' or '1', indicating whether results should be sorted in
increasing or decreasing order according to that field. 0==Decreasing is
- the default. Sort field names can be any field name designated as a sort field
+ the default.
+ Sort field names can be any field name designated as a sort field
in the pazpar2.cfg file, or the special name 'relevance'.
</para>
</listitem>
Retrieves a detailed record. Unlike the
<link linkend="command-show">show</link> command, this command
returns metadata records before merging takes place. Parameters:
-
+
<variablelist>
<varlistentry>
<term>session</term>
<screen><![CDATA[
search.pz2?session=2044502273&command=termlist&name=author,subject
]]></screen>
-Output:
+ Output:
<screen><![CDATA[
<termlist>
<activeclients>3</activeclients>
</list>
</termlist>
]]></screen>
- </para>
-
+ </para>
+
<para>
For the special termlist name "xtargets", results
are returned about the targets which have returned the most hits.
<diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
</term>
]]></screen>
- </para>
+ </para>
</refsect2>
-
+
<refsect2 id="command-bytarget">
<title>bytarget</title>
<screen><![CDATA[
search.pz2?session=605047297&command=bytarget&id=3
]]></screen>
-
+
Example output:
<screen><
projects / pazpar2-moved-to-github.git / commitdiff