Add mtrace start/stop. Requires MTRACE define
[pazpar2-moved-to-github.git] / doc / book.xml
1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" 
4 [
5      <!ENTITY % local SYSTEM "local.ent">
6      %local;
7      <!ENTITY % entities SYSTEM "entities.ent">
8      %entities;
9      <!ENTITY % idcommon SYSTEM "common/common.ent">
10      %idcommon;
11 ]>
12 <book id="book">
13  <bookinfo>
14   <title>Pazpar2 - User's Guide and Reference</title>
15   <author>
16    <firstname>Sebastian</firstname><surname>Hammer</surname>
17   </author>
18   <author>
19    <firstname>Adam</firstname><surname>Dickmeiss</surname>
20   </author>
21   <author>
22    <firstname>Marc</firstname><surname>Cromme</surname>
23   </author>
24   <author>
25    <firstname>Jakub</firstname><surname>Skoczen</surname>
26   </author>
27   <author>
28    <firstname>Mike</firstname><surname>Taylor</surname>
29   </author>
30   <author>
31    <firstname>Dennis</firstname><surname>Schafroth</surname>
32   </author>
33   <releaseinfo>&version;</releaseinfo>
34   <copyright>
35    <year>&copyright-year;</year>
36    <holder>Index Data</holder>
37   </copyright>
38   <abstract>
39    <simpara>
40     Pazpar2 is a high-performance metasearch engine featuring
41     merging, relevance ranking, record sorting,
42     and faceted results.
43     It is middleware: it has no user interface of its own, but can be
44     configured and controlled by an XML-over-HTTP web-service to provide
45     metasearching functionality behind any user interface.
46    </simpara>
47    <simpara>
48     This document is a guide and reference to Pazpar2 version &version;.
49    </simpara>
50    <simpara>
51     <inlinemediaobject>
52      <imageobject>
53       <imagedata fileref="common/id.png" format="PNG"/>
54    </imageobject>
55     <imageobject>
56      <imagedata fileref="common/id.eps" format="EPS"/>
57    </imageobject>
58    </inlinemediaobject>
59    </simpara>
60   </abstract>
61  </bookinfo>
62  
63  <chapter id="introduction">
64   <title>Introduction</title>
65
66   <section id="what.pazpar2.is">
67   <title>What Pazpar2 is</title>
68   <para>
69    Pazpar2 is a stand-alone metasearch engine with a web-service API, designed
70    to be used either from a browser-based client (JavaScript, Flash,
71    Java applet,
72    etc.), from server-side code, or any combination of the two.
73    Pazpar2 is a highly optimized client designed to
74    search many resources in parallel. It implements record merging,
75    relevance-ranking and sorting by arbitrary data content, and facet
76    analysis for browsing purposes. It is designed to be data-model
77    independent, and is capable of working with MARC, DublinCore, or any
78    other <ulink url="&url.xml;">XML</ulink>-structured response format
79    -- <ulink url="&url.xslt;">XSLT</ulink> is used to normalize and extract
80    data from retrieval records for display and analysis. It can be used
81    against any server which supports the 
82    <ulink url="&url.z39.50;">Z39.50</ulink>, <ulink url="&url.sru;">SRU/SRW</ulink> 
83    or <ulink url="&url.solr;">SOLR</ulink> protocol. Proprietary
84    backend modules can function as connectors between these standard
85    protocols and any non-standard API, including web-site scraping, to
86    support a large number of other protocols.
87   </para>
88   <para>
89    Additional functionality such as
90    user management and attractive displays are expected to be implemented by
91    applications that use Pazpar2. Pazpar2 itself is user-interface independent.
92    Its functionality is exposed through a simple XML-based web-service API,
93    designed to be easy to use from an Ajax-enabled browser, Flash
94    animation, Java applet, etc., or from a higher-level server-side language
95    like PHP, Perl or Java. Because session information can be shared between
96    browser-based logic and server-side scripting, there is tremendous
97    flexibility in how you implement application-specific logic on top
98    of Pazpar2.
99   </para>
100   <para>
101    Once you launch a search in Pazpar2, the operation continues behind the
102    scenes. Pazpar2 connects to servers, carries out searches, and
103    retrieves, deduplicates, and stores results internally. Your application
104    code may periodically inquire about the status of an ongoing operation,
105    and ask to see records or result set facets. Results become
106    available immediately, and it is easy to build end-user interfaces than
107    feel extremely responsive, even when searching more than 100 servers
108    concurrently.
109   </para>
110   <para>
111    Pazpar2 is designed to be highly configurable. Incoming records are
112    normalized to XML/UTF-8, and then further normalized using XSLT to a
113    simple internal representation that is suitable for analysis. By
114    providing XSLT stylesheets for different kinds of result records, you
115    can configure Pazpar2 to work against different kinds of information
116    retrieval servers. Finally, metadata is extracted in a configurable
117    way from this internal record, to support display, merging, ranking,
118    result set facets, and sorting. Pazpar2 is not bound to a specific model
119    of metadata, such as DublinCore or MARC: by providing the right
120    configuration, it can work with any combination of different kinds of data in
121    support of many different applications.
122   </para>
123   <para>
124    Pazpar2 is designed to be efficient and scalable. You can set it up to
125    search several hundred targets in parallel, or you can use it to support
126    hundreds of concurrent users. It is implemented with the same attention
127    to performance and economy that we use in our indexing engines, so that
128    you can focus on building your application without worrying about the
129    details of metasearch logic. You can devote all of your attention to
130    usability and let Pazpar2 do what it does best -- metasearch.
131   </para>
132   <para>
133    Pazpar2 is our attempt to re-think the traditional paradigms for
134    implementing and deploying metasearch logic, with an uncompromising
135    approach to performance, and attempting to make maximum use of the
136    capabilities of modern browsers. The demo user interface that
137    accompanies the distribution is but one example. If you think of new
138    ways of using Pazpar2, we hope you'll share them with us, and if we
139    can provide assistance with regards to training, design, programming,
140    integration with different backends, hosting, or support, please don't
141    hesitate to contact us. If you'd like to see functionality in Pazpar2
142    that is not there today, please don't hesitate to contact us. It may
143    already be in our development pipeline, or there might be a
144    possibility for you to help out by sponsoring development time or
145    code. Either way, get in touch and we will give you straight answers.
146   </para>
147   <para>
148    Enjoy!
149   </para>
150   <para>
151    Pazpar2 is covered by the GNU General Public License (GPL) version 2.
152    See <xref linkend="license"/> for further information.
153   </para>
154   </section>
155
156   <section id="connectors">
157   <title>Connectors to non-standard databases</title>
158   <para>
159    If you wish to connect to commercial or other databases which do not
160    support open standards, please contact Index Data on
161    <email>info@indexdata.com</email>. We have a
162    proprietary framework for building connectors that enable Pazpar2
163    to access
164    thousands of online databases, in addition to the vast number of catalogs
165    and online services that support the Z39.50/SRU/SRW/SOLR protocols.
166   </para>
167   </section>
168
169   <section id="name">
170    <title>A note on the name Pazpar2</title>
171    <para>
172     The name Pazpar2 derives from three sources.  One one hand, it is
173     Index Data's second major piece of software that does parallel
174     searching of Z39.50 targets.  On the other, it is a near-homophone
175     of Passpartout, the ever-helpful servant in Jules Verne's novel
176     Around the World in Eighty Days (who helpfully uses the language
177     of his master).  Finally, "passe par tout" means something like
178     "passes through anything" in French -- on other words, a universal
179     solution, or if you like a MasterKey.
180    </para>
181   </section>
182  </chapter>
183
184  <chapter id="installation">
185   <title>Installation</title>
186   <para>
187    The Pazpar2 package includes documentation as well
188    as the Pazpar2 server. The package also includes a simple user
189    interface called "test1", which consists of a single HTML page and a single
190    JavaScript file to illustrate the use of Pazpar2.
191   </para>
192   <para>
193    Pazpar2 depends on the following tools/libraries:
194    <variablelist>
195     <varlistentry><term><ulink url="&url.yaz;">YAZ</ulink></term>
196      <listitem>
197       <para>
198        The popular Z39.50 toolkit for the C language.
199        YAZ <emphasis>must</emphasis> be compiled with Libxml2/Libxslt support.
200       </para>
201      </listitem>
202     </varlistentry>
203     <varlistentry><term><ulink url="&url.icu;">International
204        Components for Unicode (ICU)</ulink></term>
205      <listitem>
206       <para>
207        ICU provides Unicode support for non-English languages with
208        character sets outside the range of 7bit ASCII, like
209        Greek, Russian, German and French. Pazpar2 uses the ICU
210        Unicode character conversions, Unicode normalization, case
211        folding and other fundamental operations needed in
212        tokenization, normalization and ranking of records. 
213       </para>
214       <para>
215        Compiling, linking, and usage of the ICU libraries is optional,
216        but strongly recommended for usage in an international
217        environment.  
218       </para>
219      </listitem>
220     </varlistentry>
221    </variablelist>
222   </para>
223   <para>
224    In order to compile Pazpar2, a C compiler which supports C99 or later
225    is required.
226   </para>
227
228   <section id="installation.unix">
229    <title>Installation from source on Unix (including Linux, MacOS, etc.)</title>
230    <para>
231     The latest source code for Pazpar2 is available from
232     <ulink url="&url.pazpar2.download;"/>.
233     Most Unix-based operating systems have the required
234     tools available as binary packages.
235     For example, if Libxml2/libXSLT libraries
236     are already installed as development packages, use these.
237    </para>
238    
239    <para>
240     Ensure that the development libraries and header files are
241     available on your system before compiling Pazpar2. For installation
242     of YAZ, refer to the Installation chapter of the YAZ manual at
243     <ulink url="&url.yaz.install;"/>.
244    </para>
245    <para>
246     Once the dependencies are in place, Pazpar2 can be unpacked and
247     installed as follows:
248    </para>
249    <screen>
250     tar xzf pazpar2-VERSION.tar.gz
251     cd pazpar2-VERSION
252     ./configure
253     make
254     sudo make install
255    </screen>
256    <para>
257     The <literal>make install</literal> will install manpages as well as the
258     Pazpar2 server, <literal>pazpar2</literal>, 
259     in PREFIX<literal>/sbin</literal>.
260     By default, PREFIX is <literal>/usr/local/</literal> . This can be
261     changed with configure option <option>--prefix</option>.
262    </para>
263   </section>
264
265   <section id="installation.win32">
266     <title>Installation from source on Windows</title>
267     <para>
268       Pazpar2 can be built for Windows using
269       <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink>.
270       The support files for building YAZ on Windows are located in the
271       <filename>win</filename> directory. The compilation is performed
272       using the <filename>win/makefile</filename> which is to be
273       processed by the NMAKE utility part of Visual Studio.
274     </para>
275     <para>
276       Ensure that the development libraries and header files are
277       available on your system before compiling Pazpar2. For installation
278       of YAZ, refer to
279       the Installation chapter of the YAZ manual at
280       <ulink url="&url.yaz.install;"/>.
281       It is easiest if YAZ and Pazpar2 are unpacked in the same
282       directory (side-by-side).
283     </para>
284     <para>
285       The compilation is tuned by editing the makefile of Pazpar2.
286       The process is similar to YAZ. Adjust the various directories
287       <literal>YAZ_DIR</literal>, <literal>ZLIB_DIR</literal>, etc.,
288       as required.
289     </para>
290     <para>
291       Compile Pazpar2 by invoking <application>nmake</application> in
292       the <filename>win</filename> directory.
293       The resulting binaries of the build process are located in the
294       <filename>bin</filename> of the Pazpar2 source
295       tree - including the <filename>pazpar2.exe</filename> and necessary DLLs.
296     </para>
297     <para>
298       The Windows version of Pazpar2 is a console application. It may
299       be installed as a Windows Service by adding option 
300       <literal>-install</literal> for the pazpar2 program. This will
301       register Pazpar2 as a service and use the other options provided
302       in the same invocation. For example:
303       <screen>
304         cd \MyPazpar2\etc
305         ..\bin\pazpar2 -install -f pazpar2.cfg -l pazpar2.log
306       </screen>
307       The Pazpar2 service may now be controlled via the Service Control
308       Panel. It may be unregistered by passing the <literal>-remove</literal>
309       option. Example:
310       <screen>
311         cd \MyPazpar2\etc
312         ..\bin\pazpar2 -remove
313       </screen>
314     </para>
315   </section>
316
317   <section id="installation.test1">
318    <title>Installation of test interfaces</title>
319    <para>
320     In this section we show how to make available the set of simple
321     interfaces that are part of the Pazpar2 source package, and which
322     demonstrate some ways to use Pazpar2.  (Note that Debian users can 
323     save time by just installing the package <literal>pazpar2-test1</literal>.)
324    </para>
325    <para>
326     A web server, such as Apache, must be installed and running on the system.
327    </para>
328
329    <para>
330     Start the Pazpar2 daemon using the 'in-source' binary of the Pazpar2
331     daemon. On Unix the process is:
332     <screen>
333      cd etc
334      cp pazpar2.cfg.dist pazpar2.cfg
335      ../src/pazpar2 -f pazpar2.cfg
336     </screen>
337     And on Windows:
338     <screen>
339      cd etc
340      copy pazpar2.cfg.dist pazpar2.cfg
341      ..\bin\pazpar2 -f pazpar2.cfg
342     </screen>
343     This will start a Pazpar2 listener on port 9004. It will proxy 
344     HTTP requests to port 80 on localhost, which we assume will be the regular
345     HTTP server on the system. Inspect and modify pazpar2.cfg as needed
346     if this is to be changed. The pazpar2.cfg file includes settings from the
347     file <filename>settings/edu.xml</filename>
348     to use for searches.
349    </para>
350
351    <para>
352     The test UIs are located in <literal>www</literal>. Ensure that this
353     directory is available to the web server by copying
354     <literal>www</literal> to the document root, 
355     using Apache's <literal>Alias</literal> directive, or
356     creating a symbolic link: for example, on a Debian or Ubuntu
357     system with Apache2 installed from the standard package, you might
358     make the link as follows:
359     <screen>
360      cd .../pazpar2
361      sudo ln -s `pwd`/www /var/www/pazpar2-demo
362     </screen>
363    </para>
364    
365    <para>
366     This makes the test applications visible at
367     <ulink url="http://localhost/pazpar2-demo/"/>
368     but they can not be run successfully from that URL, as they submit
369     search requests back to the server form which they were served,
370     and Apache2 doesn't know how to handle them.  Instead, the test
371     applications must be accessed from Pazpar2 itself, acting as a
372     proxy to Apache2, at the URL
373     <ulink url="http://localhost:9004/pazpar2-demo/"/>
374    </para>
375
376    <para>
377     From here, the demo applications can be
378     accessed: <literal>test1</literal>, <literal>test2</literal> and
379     <literal>jsdemo</literal>
380     are pure HTML+JavaScript setups, needing no server-side
381     intelligence; 
382     <literal>demo</literal>
383     requires PHP on the server.
384    </para>
385    <para>
386     If you don't see the test interfaces, check whether they are available
387     on port 80 (i.e. directly from the Apache2 server).  If not, the
388     Apache configuration is incorrect.
389    </para>
390    <para>
391     In order to use Apache as frontend for the interface on port 80
392     for public access etc., refer to 
393     <xref linkend="installation.apache2proxy"/>.
394    </para>
395   </section>
396
397   <section id="installation.debian">
398    <title>Installation on Debian or Ubuntu GNU/Linux</title>
399    <para>
400     Index Data provides Debian and Ubuntu packages for Pazpar2.
401     As of February 2010, these
402     are prepared for Debian versions Etch, Lenny and Squeeze; and for
403     Ubuntu versions 8.04 (hardy), 8.10 (intrepid), 9.04 (jaunty) and
404     9.10 (karmic).  These packages are available at
405     <ulink url="&url.pazpar2.download.debian;"/> and
406     <ulink url="&url.pazpar2.download.ubuntu;"/>.
407    </para>
408   </section>
409
410   <section id="installation.apache2proxy">
411    <title>Apache 2 Proxy</title>
412    <para>
413     Apache 2 has a 
414     <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
415      proxy module
416     </ulink> which allows Pazpar2 to become a backend to an Apache 2
417     based web service. The Apache 2 proxy must operate in the
418     <emphasis>Reverse</emphasis> Proxy mode.
419    </para>
420    
421    <para>
422     On a Debian based Apache 2 system, the relevant modules can
423     be enabled with:
424     <screen>
425      sudo a2enmod proxy_http proxy_balancer
426     </screen>
427    </para>
428
429    <para>
430     Traditionally Pazpar2 interprets URL paths with suffix 
431     <literal>/search.pz2</literal>.
432     The 
433     <ulink 
434      url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass"
435      >ProxyPass</ulink> directive of Apache must be used to map a URL path
436     the the Pazpar2 server (listening port).
437    </para>
438
439    <note>
440     <para>
441      The ProxyPass directive takes a prefix rather than
442      a suffix as URL path. It is important that the Java Script code
443      uses the prefix given for it.
444     </para>
445    </note>
446
447    <example id="installation.apache2proxy.example">
448     <title>Apache 2 proxy configuration</title>
449     <para>
450      If Pazpar2 is running on port 8004 and the portal is using
451      <filename>search.pz2</filename> inside portal in directory
452      <filename>/myportal/</filename> we could use the following
453      Apache 2 configuration:
454
455      <screen><![CDATA[
456       <IfModule mod_proxy.c>
457        ProxyRequests Off
458       
459        <Proxy *>
460         AddDefaultCharset off
461         Order deny,allow
462         Allow from all
463        </Proxy>
464       
465        ProxyPass /myportal/search.pz2 http://localhost:8004/search.pz2
466        ProxyVia Off
467       </IfModule>
468       ]]></screen>
469     </para>
470    </example>
471   </section>
472
473  </chapter>
474
475  <chapter id="using">
476   <title>Using Pazpar2</title>
477   <para>
478    This chapter provides a general introduction to the use and
479    deployment of Pazpar2. 
480   </para>
481
482   <section id="architecture">
483    <title>Pazpar2 and your systems architecture</title>
484    <para>
485     Pazpar2 is designed to provide asynchronous, behind-the-scenes
486     metasearching functionality to your application, exposing this
487     functionality using a simple webservice API that can be accessed
488     from any number of development environments. In particular, it is
489     possible to combine Pazpar2 either with your server-side dynamic
490     website scripting, with scripting or code running in the browser, or
491     with any combination of the two. Pazpar2 is an excellent tool for
492     building advanced, Ajax-based user interfaces for metasearch
493     functionality, but it isn't a requirement -- you can choose to use
494     Pazpar2 entirely as a backend to your regular server-side scripting.
495     When you do use Pazpar2 in conjunction
496     with browser scripting (JavaScript/Ajax, Flash, applets,
497     etc.), there are    special considerations.
498    </para>
499
500    <para>
501     Pazpar2 implements a simple but efficient HTTP server, and it is
502     designed to interact directly with scripting running in the browser
503     for the best possible performance, and to limit overhead when
504     several browser clients generate numerous webservice requests.
505     However, it is still desirable to use a conventional webserver,
506     such as Apache, to serve up graphics, HTML documents, and
507     server-side scripting. Because the security sandbox environment of
508     most browser-side programming environments only allows communication
509     with the server from which the enclosing HTML page or object
510     originated, Pazpar2 is designed so that it can act as a transparent
511     proxy in front of an existing webserver (see <xref
512      linkend="pazpar2_conf"/> for details). 
513     In this mode, all regular
514     HTTP requests are transparently passed through to your webserver,
515     while Pazpar2 only intercepts search-related webservice requests.
516    </para>
517
518    <para>
519     If you want to expose your combined service on port 80, you can
520     either run your regular webserver on a different port, a different
521     server, or a different IP address associated with the same server.
522    </para>
523
524    <para>
525     Pazpar2 can also work behind
526     a reverse Proxy. Refer to <xref linkend="installation.apache2proxy"/>)
527     for more information.
528     This allows your existing HTTP server to operate on port 80 as usual.
529     Pazpar2 can be started on another (internal) port.
530    </para>
531
532    <para>
533     Sometimes, it may be necessary to implement functionality on your
534     regular webserver that makes use of search results, for example to
535     implement data import functionality, emailing results, history
536     lists, personal citation lists, interlibrary loan functionality,
537     etc. Fortunately, it is simple to exchange information between
538     Pazpar2, your browser scripting, and backend server-side scripting.
539     You can send a session ID and possibly a record ID from your browser
540     code to your server code, and from there use Pazpar2s webservice API
541     to access result sets or individual records. You could even 'hide'
542     all of Pazpar2s functionality between your own API implemented on
543     the server-side, and access that from the browser or elsewhere. The
544     possibilities are just about endless.
545    </para>
546   </section>
547
548   <section id="data_model">
549    <title>Your data model</title>
550    <para>
551     Pazpar2 does not have a preconceived model of what makes up a data
552     model. There are no assumptions that records have specific fields or
553     that they are organized in any particular way. The only assumption
554     is that data comes packaged in a form that the software can work
555     with (presently, that means XML or MARC), and that you can provide
556     the necessary information to massage it into Pazpar2's internal
557     record abstraction.
558    </para>
559
560    <para>
561     Handling retrieval records in Pazpar2 is a two-step process. First,
562     you decide which data elements of the source record you are
563     interested in, and you specify any desired massaging or combining of
564     elements using an XSLT stylesheet (MARC records are automatically
565     normalized to <ulink url="&url.marcxml;">MARCXML</ulink> before this step).
566     If desired, you can run multiple XSLT stylesheets in series to accomplish
567     this, but the output of the last one should be a representation of the
568     record in a schema that Pazpar2 understands.
569    </para>
570
571    <para>
572     The intermediate, internal representation of the record looks like
573     this:
574     <screen><![CDATA[
575      <record   xmlns="http://www.indexdata.com/pazpar2/1.0"
576      mergekey="title The Shining author King, Stephen">
577
578      <metadata type="title">The Shining</metadata>
579
580      <metadata type="author">King, Stephen</metadata>
581
582      <metadata type="kind">ebook</metadata>
583
584      <!-- ... and so on -->
585     </record>
586      ]]></screen>
587
588     As you can see, there isn't much to it. There are really only a few
589     important elements to this file.
590    </para>
591
592    <para>
593     Elements should belong to the namespace
594     <literal>http://www.indexdata.com/pazpar2/1.0</literal>.
595     If the root node contains the
596     attribute 'mergekey', then every record that generates the same
597     merge key (normalized for case differences, white space, and
598     truncation) will be joined into a cluster. In other words, you
599     decide how records are merged. If you don't include a merge key,
600     records are never merged. The 'metadata' elements provide the meat
601     of the elements -- the content. the 'type' attribute is used to
602     match each element against processing rules that determine what
603     happens to the data element next.
604    </para>
605
606    <para>
607     The next processing step is the extraction of metadata from the
608     intermediate representation of the record. This is governed by the
609     'metadata' elements in the 'service' section of the configuration
610     file. See <xref linkend="config-server"/> for details. The metadata
611     in the retrieval record ultimately drives merging, sorting, ranking,
612     the extraction of browse facets, and display, all configurable.
613    </para>
614   </section>
615
616   <section id="client">
617    <title>Client development overview</title>
618    <para>
619     You can use Pazpar2 from any environment that allows you to use
620     webservices. The initial goal of the software was to support
621     Ajax-based applications, but there literally are no limits to what
622     you can do. You can use Pazpar2 from Javascript, Flash, Java, etc.,
623     on the browser side, and from any development environment on the
624     server side, and you can pass session tokens and record IDs freely
625     around between these environments to build sophisticated applications.
626     Use your imagination.
627    </para>
628
629    <para>
630     The webservice API of Pazpar2 is described in detail in <xref
631      linkend="pazpar2_protocol"/>.
632    </para>
633
634    <para>
635     In brief, you use the 'init' command to create a session, a
636     temporary workspace which carries information about the current
637     search. You start a new search using the 'search' command. Once the
638     search has been started, you can follow its progress using the
639     'stat', 'bytarget', 'termlist', or 'show' commands. Detailed records
640     can be fetched using the 'record' command.
641    </para>
642   </section>
643
644   &sect-ajaxdev;
645
646   <section id="nonstandard">
647    <title>Connecting to non-standard resources</title>
648    <para>
649     Pazpar2 uses Z39.50 as its switchboard language -- i.e. as far as it
650     is concerned, all resources speak Z39.50, its webservices derivatives,
651     SRU/SRW and SOLR servers exposing Lucene indexes. It is, however, equipped
652     to handle a broad range of different server behavior, through
653     configurable query mapping and record normalization. If you develop
654     configuration, stylesheets, etc., for a new type of resources, we
655     encourage you to share your work. But you can also use Pazpar2 to
656     connect to hundreds of resources that do not support standard
657     protocols.
658    </para>
659
660    <para>
661     For a growing number of resources, Z39.50 is all you need. Over the
662     last few years, a number of commercial, full-text resources have
663     implemented Z39.50. These can be used through Pazpar2 with little or
664     no effort. Resources that use non-standard record formats will
665     require a bit of XSLT work, but that's all.
666    </para>
667
668    <para>
669     But what about resources that don't support Z39.50 at all? Some resources might
670     support OpenSearch, private, XML/HTTP-based protocols, or something
671     else entirely. Some databases exist only as web user interfaces and
672     will require screen-scraping. Still others exist only as static
673     files, or perhaps as databases supporting the OAI-PMH protocol.
674     There is hope! Read on.
675    </para>
676
677    <para>
678     Index Data continues to advocate the support of open standards. We
679     work with database vendors to support standards, so you don't have
680     to worry about programming against non-standard services. We also
681     provide tools (see <ulink
682      url="http://www.indexdata.com/simpleserver">SimpleServer</ulink>)
683     which make it comparatively easy to build gateways against servers
684     with non-standard behavior. Again, we encourage you to share any
685     work you do in this direction.
686    </para>
687
688    <para>
689     But the bottom line is that working with non-standard resources in
690     metasearching is really, really hard. If you want to build a
691     project with Pazpar2, and you need access to resources with
692     non-standard interfaces, we can help. We run gateways to more than
693     2,000 popular, commercial databases and other resources,
694     making it simple 
695     to plug them directly into Pazpar2. For a small annual fee per
696     database, we can help you establish connections to your licensed
697     resources. Meanwhile, you can help! If you build your own
698     standards-compliant gateways, host them for others, or share the
699     code! And tell your vendors that they can save everybody money and
700     increase the appeal of their resources by supporting standards.
701    </para>
702
703    <para>
704     There are those who will ask us why we are using Z39.50 as our
705     switchboard language rather than a different protocol. Basically,
706     we believe that Z39.50 is presently the most widely implemented 
707     information retrieval protocol that has the level of functionality
708     required to support a good metasearching experience (structured
709     searching, structured, well-defined results). It is also compact and
710     efficient, and there is a very broad range of tools available to
711     implement it.
712    </para>
713   </section>
714
715   <section id="unicode">
716    <title>Unicode Compliance</title>
717    <para>
718     Pazpar2 is Unicode compliant and language and locale aware but relies
719     on character encoding for the targets to be specified correctly if
720     the targets themselves are not UTF-8 based (most aren't).
721     Just a few bad behaving targets can spoil the search experience
722     considerably if for example Greek, Russian or otherwise non 7-bit ASCII
723     search terms are entered. In these cases some targets return
724     records irrelevant to the query, and the result screens will be
725     cluttered with noise.
726    </para>
727    <para>
728     While noise from misbehaving targets can not be removed, it can
729     be reduced using truly Unicode based ranking. This is an
730     option which is available to the system administrator if ICU
731     support is compiled into Pazpar2, see
732     <xref linkend="installation"/> for details.
733    </para>
734    <para>
735     In addition, the ICU tokenization and normalization rules must
736     be defined in the master configuration file described in 
737     <xref linkend="config-server"/>.
738    </para>
739   </section>
740
741   <section id="load_balancing">
742    <title>Load balancing</title>
743    <para>
744      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">
745      mod_proxy_balancer
746     </ulink> module in your Apache2 installation.
747    </para>
748    
749    <para>
750     On a Debian based Apache 2 system, the relevant modules can
751     be enabled with:
752     <screen>
753      sudo a2enmod proxy_http
754     </screen>
755    </para>
756
757    <para>
758      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.
759    </para>
760
761    <example id="load_balancing.example">
762     <title>Apache 2 load balancing configuration</title>
763     <para>
764      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:
765
766      <screen><![CDATA[
767        <Proxy *>
768          AddDefaultCharset off
769          Order deny,allow
770          Allow from all
771        </Proxy>
772        ProxyVia Off
773
774        # 'route' has to match the configured pazpar2 server ID
775        <Proxy balancer://pz2cluster>
776          BalancerMember http://localhost:8004 route=pz1
777          BalancerMember http://localhost:8005 route=pz2
778          BalancerMember http://localhost:8006 route=pz3
779          BalancerMember http://localhost:8007 route=pz4
780        </Proxy>
781
782        # route is resent in the 'session' param which has the form: 
783        # 'sessid.serverid', understandable by the mod_proxy_load_balancer
784        # this is not going to work if the client tampers with the 'session' param
785        ProxyPass /pazpar2/search.pz2 balancer://pz2cluster lbmethod=byrequests stickysession=session nofailover=On]]></screen>
786
787      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.
788    </para>
789
790   </example>
791
792   </section>
793
794
795  </chapter> <!-- Using Pazpar2 -->
796
797  <reference id="reference">
798   <title>Reference</title>
799   <partintro id="reference-introduction">
800    <para>
801     The material in this chapter is drawn directly from the individual
802     manual entries.
803    </para>
804   </partintro>
805   &manref;
806  </reference>
807
808  <appendix id="license"><title>License</title>
809   
810    <para>
811     Pazpar2,
812     Copyright &copy; &copyright-year; Index Data.
813    </para>
814    
815    <para>
816     Pazpar2 is free software; you can redistribute it and/or modify it under
817     the terms of the GNU General Public License as published by the Free
818     Software Foundation; either version 2, or (at your option) any later
819     version.
820    </para>
821    
822    <para>
823     Pazpar2 is distributed in the hope that it will be useful, but WITHOUT ANY
824     WARRANTY; without even the implied warranty of MERCHANTABILITY or
825     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
826     for more details.
827    </para>
828    
829    <para>
830     You should have received a copy of the GNU General Public License
831     along with Pazpar2; see the file LICENSE.  If not, write to the
832     Free Software Foundation, 
833     51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
834    </para>
835
836  </appendix>
837
838  &gpl2;
839  
840 </book>
841
842  <!-- Keep this comment at the end of the file
843  Local variables:
844  mode: sgml
845  sgml-omittag:t
846  sgml-shorttag:t
847  sgml-minimize-attributes:nil
848  sgml-always-quote-attributes:t
849  sgml-indent-step:1
850  sgml-indent-data:t
851  sgml-parent-document: nil
852  sgml-local-catalogs: nil
853  sgml-namecase-general:t
854  End:
855  -->