Merge branch 'master' of ssh://git.indexdata.com/home/git/pub/pazpar2
[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
121     in 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 GNU/Linux and Ubuntu</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
415         url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
416      proxy module
417     </ulink>
418     which allows Pazpar2 to become a backend to an Apache 2
419     based web service. The Apache 2 proxy must operate in the
420     <emphasis>Reverse</emphasis> Proxy mode.
421    </para>
422    
423    <para>
424     On a Debian based Apache 2 system, the relevant modules can
425     be enabled with:
426     <screen>
427      sudo a2enmod proxy_http proxy_balancer
428     </screen>
429    </para>
430    
431    <para>
432     Traditionally Pazpar2 interprets URL paths with suffix 
433     <literal>/search.pz2</literal>.
434     The 
435     <ulink
436         url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass">
437     ProxyPass
438     </ulink>
439     directive of Apache must be used to map a URL path
440     the the Pazpar2 server (listening port).
441    </para>
442
443    <note>
444     <para>
445      The ProxyPass directive takes a prefix rather than
446      a suffix as URL path. It is important that the Java Script code
447      uses the prefix given for it.
448     </para>
449    </note>
450
451    <example id="installation.apache2proxy.example">
452     <title>Apache 2 proxy configuration</title>
453     <para>
454      If Pazpar2 is running on port 8004 and the portal is using
455      <filename>search.pz2</filename> inside portal in directory
456      <filename>/myportal/</filename> we could use the following
457      Apache 2 configuration:
458
459      <screen><![CDATA[
460       <IfModule mod_proxy.c>
461        ProxyRequests Off
462       
463        <Proxy *>
464         AddDefaultCharset off
465         Order deny,allow
466         Allow from all
467        </Proxy>
468       
469        ProxyPass /myportal/search.pz2 http://localhost:8004/search.pz2
470        ProxyVia Off
471       </IfModule>
472       ]]></screen>
473     </para>
474    </example>
475   </section>
476   
477  </chapter>
478  
479  <chapter id="using">
480   <title>Using Pazpar2</title>
481   <para>
482    This chapter provides a general introduction to the use and
483    deployment of Pazpar2. 
484   </para>
485   
486   <section id="architecture">
487    <title>Pazpar2 and your systems architecture</title>
488    <para>
489     Pazpar2 is designed to provide asynchronous, behind-the-scenes
490     metasearching functionality to your application, exposing this
491     functionality using a simple webservice API that can be accessed
492     from any number of development environments. In particular, it is
493     possible to combine Pazpar2 either with your server-side dynamic
494     website scripting, with scripting or code running in the browser, or
495     with any combination of the two. Pazpar2 is an excellent tool for
496     building advanced, Ajax-based user interfaces for metasearch
497     functionality, but it isn't a requirement -- you can choose to use
498     Pazpar2 entirely as a backend to your regular server-side scripting.
499     When you do use Pazpar2 in conjunction
500     with browser scripting (JavaScript/Ajax, Flash, applets,
501     etc.), there are    special considerations.
502    </para>
503
504    <para>
505     Pazpar2 implements a simple but efficient HTTP server, and it is
506     designed to interact directly with scripting running in the browser
507     for the best possible performance, and to limit overhead when
508     several browser clients generate numerous webservice requests.
509     However, it is still desirable to use a conventional webserver,
510     such as Apache, to serve up graphics, HTML documents, and
511     server-side scripting. Because the security sandbox environment of
512     most browser-side programming environments only allows communication
513     with the server from which the enclosing HTML page or object
514     originated, Pazpar2 is designed so that it can act as a transparent
515     proxy in front of an existing webserver (see <xref
516     linkend="pazpar2_conf"/> for details). 
517     In this mode, all regular
518     HTTP requests are transparently passed through to your webserver,
519     while Pazpar2 only intercepts search-related webservice requests.
520    </para>
521
522    <para>
523     If you want to expose your combined service on port 80, you can
524     either run your regular webserver on a different port, a different
525     server, or a different IP address associated with the same server.
526    </para>
527
528    <para>
529     Pazpar2 can also work behind
530     a reverse Proxy. Refer to <xref linkend="installation.apache2proxy"/>)
531     for more information.
532     This allows your existing HTTP server to operate on port 80 as usual.
533     Pazpar2 can be started on another (internal) port.
534    </para>
535
536    <para>
537     Sometimes, it may be necessary to implement functionality on your
538     regular webserver that makes use of search results, for example to
539     implement data import functionality, emailing results, history
540     lists, personal citation lists, interlibrary loan functionality,
541     etc. Fortunately, it is simple to exchange information between
542     Pazpar2, your browser scripting, and backend server-side scripting.
543     You can send a session ID and possibly a record ID from your browser
544     code to your server code, and from there use Pazpar2s webservice API
545     to access result sets or individual records. You could even 'hide'
546     all of Pazpar2s functionality between your own API implemented on
547     the server-side, and access that from the browser or elsewhere. The
548     possibilities are just about endless.
549    </para>
550   </section>
551
552   <section id="data_model">
553    <title>Your data model</title>
554    <para>
555     Pazpar2 does not have a preconceived model of what makes up a data
556     model. There are no assumptions that records have specific fields or
557     that they are organized in any particular way. The only assumption
558     is that data comes packaged in a form that the software can work
559     with (presently, that means XML or MARC), and that you can provide
560     the necessary information to massage it into Pazpar2's internal
561     record abstraction.
562    </para>
563
564    <para>
565     Handling retrieval records in Pazpar2 is a two-step process. First,
566     you decide which data elements of the source record you are
567     interested in, and you specify any desired massaging or combining of
568     elements using an XSLT stylesheet (MARC records are automatically
569     normalized to <ulink url="&url.marcxml;">MARCXML</ulink> before this step).
570     If desired, you can run multiple XSLT stylesheets in series to accomplish
571     this, but the output of the last one should be a representation of the
572     record in a schema that Pazpar2 understands.
573    </para>
574
575    <para>
576     The intermediate, internal representation of the record looks like
577     this:
578     <screen><![CDATA[
579      <record   xmlns="http://www.indexdata.com/pazpar2/1.0"
580      mergekey="title The Shining author King, Stephen">
581
582      <metadata type="title" rank="2">The Shining</metadata>
583
584      <metadata type="author">King, Stephen</metadata>
585
586      <metadata type="kind">ebook</metadata>
587
588      <!-- ... and so on -->
589     </record>
590      ]]></screen>
591     
592     As you can see, there isn't much to it. There are really only a few
593     important elements to this file.
594    </para>
595    
596    <para>
597     Elements should belong to the namespace
598     <literal>http://www.indexdata.com/pazpar2/1.0</literal>.
599     If the root node contains the
600     attribute 'mergekey', then every record that generates the same
601     merge key (normalized for case differences, white space, and
602     truncation) will be joined into a cluster. In other words, you
603     decide how records are merged. If you don't include a merge key,
604     records are never merged. The 'metadata' elements provide the meat
605     of the elements -- the content. the 'type' attribute is used to
606     match each element against processing rules that determine what
607     happens to the data element next. The attribute, 'rank' specifies
608     specifies a multipler for ranking for this element.
609    </para>
610
611    <para>
612     The next processing step is the extraction of metadata from the
613     intermediate representation of the record. This is governed by the
614     'metadata' elements in the 'service' section of the configuration
615     file. See <xref linkend="config-server"/> for details. The metadata
616     in the retrieval record ultimately drives merging, sorting, ranking,
617     the extraction of browse facets, and display, all configurable.
618    </para>
619   </section>
620
621   <section id="client">
622    <title>Client development overview</title>
623    <para>
624     You can use Pazpar2 from any environment that allows you to use
625     webservices. The initial goal of the software was to support
626     Ajax-based applications, but there literally are no limits to what
627     you can do. You can use Pazpar2 from Javascript, Flash, Java, etc.,
628     on the browser side, and from any development environment on the
629     server side, and you can pass session tokens and record IDs freely
630     around between these environments to build sophisticated applications.
631     Use your imagination.
632    </para>
633
634    <para>
635     The webservice API of Pazpar2 is described in detail in <xref
636      linkend="pazpar2_protocol"/>.
637    </para>
638    
639    <para>
640     In brief, you use the 'init' command to create a session, a
641     temporary workspace which carries information about the current
642     search. You start a new search using the 'search' command. Once the
643     search has been started, you can follow its progress using the
644     'stat', 'bytarget', 'termlist', or 'show' commands. Detailed records
645     can be fetched using the 'record' command.
646    </para>
647   </section>
648
649   &sect-ajaxdev;
650
651   <section id="nonstandard">
652    <title>Connecting to non-standard resources</title>
653    <para>
654     Pazpar2 uses Z39.50 as its switchboard language -- i.e. as far as it
655     is concerned, all resources speak Z39.50, its webservices derivatives,
656     SRU/SRW and SOLR servers exposing Lucene indexes. It is, however, equipped
657     to handle a broad range of different server behavior, through
658     configurable query mapping and record normalization. If you develop
659     configuration, stylesheets, etc., for a new type of resources, we
660     encourage you to share your work. But you can also use Pazpar2 to
661     connect to hundreds of resources that do not support standard
662     protocols.
663    </para>
664
665    <para>
666     For a growing number of resources, Z39.50 is all you need. Over the
667     last few years, a number of commercial, full-text resources have
668     implemented Z39.50. These can be used through Pazpar2 with little or
669     no effort. Resources that use non-standard record formats will
670     require a bit of XSLT work, but that's all.
671    </para>
672    
673    <para>
674     But what about resources that don't support Z39.50 at all?
675     Some resources might support OpenSearch, private, XML/HTTP-based
676     protocols, or something else entirely.
677     Some databases exist only as web user interfaces and
678     will require screen-scraping. Still others exist only as static
679     files, or perhaps as databases supporting the OAI-PMH protocol.
680     There is hope! Read on.
681    </para>
682
683    <para>
684     Index Data continues to advocate the support of open standards. We
685     work with database vendors to support standards, so you don't have
686     to worry about programming against non-standard services. We also
687     provide tools (see <ulink
688     url="http://www.indexdata.com/simpleserver">SimpleServer</ulink>)
689     which make it comparatively easy to build gateways against servers
690     with non-standard behavior. Again, we encourage you to share any
691     work you do in this direction.
692    </para>
693    
694    <para>
695     But the bottom line is that working with non-standard resources in
696     metasearching is really, really hard. If you want to build a
697     project with Pazpar2, and you need access to resources with
698     non-standard interfaces, we can help. We run gateways to more than
699     2,000 popular, commercial databases and other resources,
700     making it simple 
701     to plug them directly into Pazpar2. For a small annual fee per
702     database, we can help you establish connections to your licensed
703     resources. Meanwhile, you can help! If you build your own
704     standards-compliant gateways, host them for others, or share the
705     code! And tell your vendors that they can save everybody money and
706     increase the appeal of their resources by supporting standards.
707    </para>
708
709    <para>
710     There are those who will ask us why we are using Z39.50 as our
711     switchboard language rather than a different protocol. Basically,
712     we believe that Z39.50 is presently the most widely implemented 
713     information retrieval protocol that has the level of functionality
714     required to support a good metasearching experience (structured
715     searching, structured, well-defined results). It is also compact and
716     efficient, and there is a very broad range of tools available to
717     implement it.
718    </para>
719   </section>
720
721   <section id="unicode">
722    <title>Unicode Compliance</title>
723    <para>
724     Pazpar2 is Unicode compliant and language and locale aware but relies
725     on character encoding for the targets to be specified correctly if
726     the targets themselves are not UTF-8 based (most aren't).
727     Just a few bad behaving targets can spoil the search experience
728     considerably if for example Greek, Russian or otherwise non 7-bit ASCII
729     search terms are entered. In these cases some targets return
730     records irrelevant to the query, and the result screens will be
731     cluttered with noise.
732    </para>
733    <para>
734     While noise from misbehaving targets can not be removed, it can
735     be reduced using truly Unicode based ranking. This is an
736     option which is available to the system administrator if ICU
737     support is compiled into Pazpar2, see
738     <xref linkend="installation"/> for details.
739    </para>
740    <para>
741     In addition, the ICU tokenization and normalization rules must
742     be defined in the master configuration file described in 
743     <xref linkend="config-server"/>.
744    </para>
745   </section>
746
747   <section id="load_balancing">
748    <title>Load balancing</title>
749    <para>
750      Just like any web server, Pazpar2, can be load balanced by a standard
751      hardware or software load balancer as long as the session stickiness
752      is ensured. If you are already running the Apache2 web server in front
753      of Pazpar2 and use the apache mod_proxy module to 'relay' client
754      requests to Pazpar2, this set up can be easily extended to include
755      load balancing capabilites.
756      To do so you need to enable the
757      <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html">
758       mod_proxy_balance
759      </ulink>
760      module in your Apache2 installation.
761    </para>
762    
763    <para>
764     On a Debian based Apache 2 system, the relevant modules can
765     be enabled with:
766     <screen>
767      sudo a2enmod proxy_http
768     </screen>
769    </para>
770
771    <para>
772     The mod_proxy_balancer can pass all 'sessionsticky' requests to the
773     same backend worker as long as the requests are marked with the
774     originating worker's ID (called 'route'). If the Pazpar2 serverID is
775     configured (by setting an 'id' attribute on the 'server' element in
776     the Pazpar2 configuration file) Pazpar2 will append it to the
777     'session' element returned during the 'init' in a mod_proxy_balancer
778     compatible manner.
779     Since the 'session' is then re-sent by the client (for all pazpar2
780     request besides 'init'), the balancer can use the marker to pass
781     the request to the right route. To do so the balancer needs to be
782     configured to inspect the 'session' parameter.
783    </para>
784
785    <example id="load_balancing.example">
786     <title>Apache 2 load balancing configuration</title>
787     <para>
788      Having 4 Pazpar2 instances running on the same host, port range of
789      8004-8007 and serverIDs of: pz1, pz2, pz3 and pz4 respectively we
790      could use the following Apache 2 configuration to expose a single
791      pazpar2 'endpoint' on a standard
792      (<filename>/pazpar2/search.pz2</filename>) location:
793      
794      <screen><![CDATA[
795        <Proxy *>
796          AddDefaultCharset off
797          Order deny,allow
798          Allow from all
799        </Proxy>
800        ProxyVia Off
801
802        # 'route' has to match the configured pazpar2 server ID
803        <Proxy balancer://pz2cluster>
804          BalancerMember http://localhost:8004 route=pz1
805          BalancerMember http://localhost:8005 route=pz2
806          BalancerMember http://localhost:8006 route=pz3
807          BalancerMember http://localhost:8007 route=pz4
808        </Proxy>
809
810        # route is resent in the 'session' param which has the form: 
811        # 'sessid.serverid', understandable by the mod_proxy_load_balancer
812        # this is not going to work if the client tampers with the 'session' param
813        ProxyPass /pazpar2/search.pz2 balancer://pz2cluster lbmethod=byrequests stickysession=session nofailover=On
814      ]]></screen>
815      
816      The 'ProxyPass' line sets up a reverse proxy for request
817      ‘/pazpar2/search.pz2’ and delegates all requests to the load balancer
818      (virtual worker) with name ‘pz2cluster’.
819      Sticky sessions are enabled and implemented using the ‘session’ parameter.
820      The ‘Proxy’ section lists all the servers (real workers) which the
821      load balancer can use.
822     </para>
823     
824    </example>
825    
826   </section>
827   
828
829  </chapter> <!-- Using Pazpar2 -->
830
831  <reference id="reference">
832   <title>Reference</title>
833   <partintro id="reference-introduction">
834    <para>
835     The material in this chapter is drawn directly from the individual
836     manual entries.
837    </para>
838   </partintro>
839   &manref;
840  </reference>
841
842  <appendix id="license">
843   <title>License</title>
844  
845  <para>
846   Pazpar2,
847   Copyright &#xa9; &copyright-year; Index Data.
848  </para>
849  
850  <para>
851   Pazpar2 is free software; you can redistribute it and/or modify it under
852   the terms of the GNU General Public License as published by the Free
853   Software Foundation; either version 2, or (at your option) any later
854   version.
855  </para>
856  
857  <para>
858   Pazpar2 is distributed in the hope that it will be useful, but WITHOUT ANY
859   WARRANTY; without even the implied warranty of MERCHANTABILITY or
860   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
861   for more details.
862  </para>
863  
864  <para>
865   You should have received a copy of the GNU General Public License
866   along with Pazpar2; see the file LICENSE.  If not, write to the
867   Free Software Foundation, 
868   51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
869  </para>
870  
871  </appendix>
872
873  &gpl2;
874  
875 </book>
876
877 <!-- Keep this comment at the end of the file
878 Local variables:
879 mode: nxml
880 nxml-child-indent: 1
881 End:
882 -->