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 -->