doc/book.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY manref SYSTEM "manref.xml">
   8      <!ENTITY progref SYSTEM "progref.xml">
   9      <!ENTITY gpl2 SYSTEM "gpl-2.0.xml">
  10      <!ENTITY % idcommon SYSTEM "common/common.ent">
  11      %idcommon;
  12      <!-- Next line allows imagedata/@format="PDF" and is taken from
  13          http://lists.oasis-open.org/archives/docbook/200303/msg00163.html
  14      -->
  15      <!ENTITY % local.notation.class "| PDF">
  16      <!-- Next line is necessary for some XML parsers, for reasons I
  17           don't understand.  I got this from
  18          http://lists.oasis-open.org/archives/docbook/200303/msg00180.html
  19      -->
  20      <!NOTATION PDF SYSTEM "PDF">
  21 ]>
  22 <book>
  23  <bookinfo>
  24   <title>Metaproxy - User's Guide and Reference</title>
  25   <authorgroup>
  26    <author>
  27     <firstname>Adam</firstname><surname>Dickmeiss</surname>
  28    </author>
  29    <author>
  30     <firstname>Marc</firstname><surname>Cromme</surname>
  31    </author>
  32    <author>
  33     <firstname>Mike</firstname><surname>Taylor</surname>
  34    </author>
  35   </authorgroup>
  36   <releaseinfo>&version;</releaseinfo>
  37   <copyright>
  38    <year>2005-2009</year>
  39    <holder>Index Data ApS</holder>
  40   </copyright>
  41   <abstract>
  42    <simpara>
  43     This manual is part of Metaproxy version &version;.
  44     </simpara>
  45    <simpara>
  46     Metaproxy is a universal router, proxy and encapsulated
  47     metasearcher for information retrieval protocols.  It accepts,
  48     processes, interprets and redirects requests from IR clients using
  49     standard protocols such as the binary
  50     <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink>
  51     and  the information search and retrieval
  52     web service <ulink url="&url.sru;">SRU</ulink>
  53     as well as functioning as a limited
  54     <ulink url="&url.http;">HTTP</ulink> server.
  55    </simpara>
  56    <simpara>
  57     Metaproxy is configured by an XML file which
  58     specifies how the software should function in terms of routes that
  59     the request packets can take through the proxy, each step on a
  60     route being an instantiation of a filter.  Filters come in many
  61     types, one for each operation: accepting Z39.50 packets, logging,
  62     query transformation, multiplexing, etc.  Further filter-types can
  63     be added as loadable modules to extend Metaproxy functionality,
  64     using the filter API.
  65    </simpara>
  66    <simpara>
  67     Metaproxy is covered by the GNU General Public License version 2.
  68    </simpara>
  69    <simpara>
  70     <inlinemediaobject>
  71      <imageobject>
  72       <imagedata fileref="common/id.png" format="PNG"/>
  73      </imageobject>
  74      <imageobject>
  75       <imagedata fileref="common/id.eps" format="EPS"/>
  76      </imageobject>
  77     </inlinemediaobject>
  78    </simpara>
  79   </abstract>
  80  </bookinfo>
  81
  82  <chapter id="introduction">
  83   <title>Introduction</title>
  84
  85   <para>
  86    <ulink url="&url.metaproxy;">Metaproxy</ulink>
  87    is a stand alone program that acts as a universal router, proxy and
  88    encapsulated metasearcher for information retrieval protocols such
  89    as <ulink url="&url.z39.50;">Z39.50</ulink> and
  90    <ulink url="&url.sru;">SRU</ulink>.
  91    To clients, it acts as a server of these protocols: it can be searched,
  92    records can be retrieved from it, etc.
  93    To servers, it acts as a client: it searches in them,
  94    retrieves records from them, etc.  it satisfies its clients'
  95    requests by transforming them, multiplexing them, forwarding them
  96    on to zero or more servers, merging the results, transforming
  97    them, and delivering them back to the client.  In addition, it
  98    acts as a simple <ulink url="&url.http;">HTTP</ulink> server; support
  99    for further protocols can be added in a modular fashion, through the
 100    creation of new filters.
 101   </para>
 102   <screen>
 103    Anything goes in!
 104    Anything goes out!
 105    Fish, bananas, cold pyjamas,
 106    Mutton, beef and trout!
 107         - attributed to Cole Porter.
 108   </screen>
 109   <para>
 110    Metaproxy is a more capable alternative to
 111    <ulink url="&url.yazproxy;">YAZ Proxy</ulink>,
 112    being more powerful, flexible, configurable and extensible.  Among
 113    its many advantages over the older, more pedestrian work are
 114    support for multiplexing (encapsulated metasearching), routing by
 115    database name, authentication and authorization and serving local
 116    files via HTTP.  Equally significant, its modular architecture
 117    facilitites the creation of pluggable modules implementing further
 118    functionality.
 119   </para>
 120   <para>
 121    This manual will describe how to install Metaproxy
 122    before giving an overview of its architecture, then discussing the
 123    key concept of a filter in some depth and giving an overview of
 124    the various filter types, then discussing the configuration file
 125    format.  After this come several optional chapters which may be
 126    freely skipped: a detailed discussion of virtual databases and
 127    multi-database searching, some notes on writing extensions
 128    (additional filter types) and a high-level description of the
 129    source code.  Finally comes the reference guide, which contains
 130    instructions for invoking the <command>metaproxy</command>
 131    program, and detailed information on each type of filter,
 132    including examples.
 133   </para>
 134  </chapter>
 135
 136  <chapter id="installation">
 137   <title>Installation</title>
 138   <para>
 139    Metaproxy depends on the following tools/libraries:
 140    <variablelist>
 141     <varlistentry><term><ulink url="&url.yazplusplus;">YAZ++</ulink></term>
 142      <listitem>
 143       <para>
 144        This is a C++ library based on <ulink url="&url.yaz;">YAZ</ulink>.
 145       </para>
 146      </listitem>
 147     </varlistentry>
 148     <varlistentry><term><ulink url="&url.libxslt;">Libxslt</ulink></term>
 149      <listitem>
 150       <para>This is an XSLT processor - based on
 151        <ulink url="&url.libxml2;">Libxml2</ulink>. Both Libxml2 and
 152        Libxslt must be installed with the development components
 153        (header files, etc.) as well as the run-time libraries.
 154       </para>
 155      </listitem>
 156     </varlistentry>
 157     <varlistentry><term><ulink url="&url.boost;">Boost</ulink></term>
 158      <listitem>
 159       <para>
 160        The popular C++ library. Initial versions of Metaproxy
 161        was built with 1.32 but this is no longer supported.
 162        Metaproxy is known to work with Boost version 1.33 through 1.38.
 163       </para>
 164      </listitem>
 165     </varlistentry>
 166    </variablelist>
 167   </para>
 168   <para>
 169    In order to compile Metaproxy a modern C++ compiler is
 170    required. Boost, in particular, requires the C++ compiler
 171    to facilitate the newest features. Refer to Boost
 172    <ulink url="&url.boost.compilers.status;">Compiler Status</ulink>
 173    for more information.
 174   </para>
 175   <para>
 176    We have successfully built Metaproxy using the compilers
 177    <ulink url="&url.gcc;">GCC</ulink> version 4.0 and
 178    <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink> 2003/2005.
 179   </para>
 180
 181   <section id="installation.unix">
 182    <title>Installation on Unix (from Source)</title>
 183    <para>
 184     Here is a quick step-by-step guide on how to compile all the
 185     tools that Metaproxy uses. Only few systems have none of the required
 186     tools binary packages. If, for example, Libxml2/libxslt are already
 187     installed as development packages use those (and omit compilation).
 188    </para>
 189
 190    <section id="libxml2.fromsource">
 191     <title>Libxml2/libxslt</title>
 192     <para>
 193      Libxml2/libxslt:
 194     </para>
 195     <screen>
 196      gunzip -c libxml2-version.tar.gz|tar xf -
 197      cd libxml2-version
 198      ./configure
 199      make
 200      su
 201      make install
 202     </screen>
 203     <screen>
 204      gunzip -c libxslt-version.tar.gz|tar xf -
 205      cd libxslt-version
 206      ./configure
 207      make
 208      su
 209      make install
 210     </screen>
 211    </section>
 212    <section id="yaz.fromsource">
 213     <title>YAZ/YAZ++</title>
 214     <screen>
 215      gunzip -c yaz-version.tar.gz|tar xf -
 216      cd yaz-version
 217      ./configure
 218      make
 219      su
 220      make install
 221     </screen>
 222     <screen>
 223      gunzip -c yazpp-version.tar.gz|tar xf -
 224      cd yazpp-version
 225      ./configure
 226      make
 227      su
 228      make install
 229     </screen>
 230    </section>
 231    <section>
 232     <title id="boost.fromsource">Boost</title>
 233     <para>
 234      Metaproxy needs components thread and test from
 235      Boost.
 236     </para>
 237     <screen>
 238      gunzip -c boost-version.tar.gz|tar xf -
 239      cd boost-version
 240      ./configure --with-libraries=thread,test --with-toolset=gcc
 241      make
 242      su
 243      make install
 244     </screen>
 245     <para>
 246      However, under the hood bjam is used. You can invoke that with
 247     </para>
 248     <screen>
 249      ./bjam --toolset=gcc --with-thread --with-test stage
 250     </screen>
 251     <para>
 252      Replace <literal>stage</literal> with <literal>clean</literal> /
 253      <literal>install</literal> to perform clean and install respectively.
 254     </para>
 255     <para>
 256      Add <literal>--prefix=DIR</literal> to install Boost in other
 257      prefix than <literal>/usr/local</literal>.
 258     </para>
 259    </section>
 260    <section id="metaproxy.fromsource">
 261     <title>Metaproxy</title>
 262     <screen>
 263      gunzip -c metaproxy-version.tar.gz|tar xf -
 264      cd metaproxy-version
 265      ./configure
 266      make
 267      su
 268      make install
 269     </screen>
 270     <para>
 271      You may have to tell configure where Boost is installed by supplying
 272      options <literal>--with-boost</literal> and <literal>--with-boost-toolset</literal>.
 273      The former sets the PREFIX for Boost (same as --prefix for Boost above).
 274      The latter the compiler toolset (eg. gcc34).
 275     </para>
 276     <para>
 277      Pass <literal>--help</literal> to configure to get a list of
 278      available options.
 279     </para>
 280    </section>
 281   </section>
 282
 283   <section id="installation.debian">
 284    <title>Installation on Debian GNU/Linux</title>
 285    <para>
 286     All dependencies for Metaproxy are available as
 287     <ulink url="&url.debian;">Debian</ulink>
 288     packages for the sarge (stable in 2005) and etch (testing in 2005)
 289     distributions.
 290    </para>
 291    <para>
 292     The procedures for Debian based systems, such as
 293     <ulink url="&url.ubuntu;">Ubuntu</ulink> is probably similar
 294    </para>
 295    <para>
 296     There is currently no official Debian package for YAZ++.
 297     And the official Debian package for YAZ is probably too old.
 298     But Index Data bulds "new" versions of those for Debian (i386 only).
 299    </para>
 300    <para>
 301     Update the <filename>/etc/apt/sources.list</filename>
 302     to include the Index Data repository.
 303     See YAZ' <ulink url="&url.yaz.download.debian;">Download Debian</ulink>
 304     for more information.
 305    </para>
 306    <screen>
 307     apt-get install libxslt1-dev
 308     apt-get install libyazpp2-dev
 309     apt-get install libboost-dev
 310     apt-get install libboost-thread-dev
 311     apt-get install libboost-test-dev
 312    </screen>
 313    <para>
 314     With these packages installed, the usual configure + make
 315     procedure can be used for Metaproxy as outlined in
 316     <xref linkend="installation.unix"/>.
 317    </para>
 318   </section>
 319
 320   <section id="installation.rpm">
 321    <title>Installation on RPM based Linux Systems</title>
 322    <para>
 323     All external dependencies for Metaproxy are available as
 324     RPM packages, either from your distribution site, or from the
 325     <ulink url="http://fr.rpmfind.net/">RPMfind</ulink> site.
 326    </para>
 327    <para>
 328     For example, an installation of the requires Boost C++ development
 329     libraries on RedHat Fedora C4 and C5 can be done like this:
 330     <screen>
 331     wget ftp://fr.rpmfind.net/wlinux/fedora/core/updates/testing/4/SRPMS/boost-1.33.0-3.fc4.src.rpm
 332     sudo rpmbuild --buildroot src/ --rebuild -p fc4/boost-1.33.0-3.fc4.src.rpm
 333     sudo rpm -U /usr/src/redhat/RPMS/i386/boost-*rpm
 334     </screen>
 335    </para>
 336    <para>
 337     The  <ulink url="&url.yaz;">YAZ</ulink> library is needed to
 338     compile &metaproxy;, see there
 339     for more information on available RPM packages.
 340    </para>
 341    <para>
 342     There is currently no official RPM package for YAZ++.
 343     See the <ulink url="&url.yazplusplus;">YAZ++</ulink> pages
 344     for more information on a Unix tarball install.
 345    </para>
 346    <para>
 347     With these packages installed, the usual configure + make
 348     procedure can be used for Metaproxy as outlined in
 349     <xref linkend="installation.unix"/>.
 350    </para>
 351   </section>
 352
 353   <section id="installation.windows">
 354    <title>Installation on Windows</title>
 355    <para>
 356     Metaproxy can be compiled with Microsoft
 357     <ulink url="&url.vstudio;">Visual Studio</ulink>.
 358     Versions 2003 (C 7.1), 2005 (C 8.0) and 2008 (C 9.0) is known to work.
 359    </para>
 360    <section id="installation.windows.boost">
 361     <title>Boost</title>
 362     <para>
 363      For Windows, it's easiest to get the precompiled Boost
 364      package from <ulink url="&url.boost.windows.download;">here</ulink>.
 365      Several versions of the Boost libraries may be selected when
 366      installing Boost for windows. Please choose at least the
 367      <emphasis>multithreaded</emphasis> (non-DLL) version because
 368      the Metaproxy makefile uses that.
 369     </para>
 370     <para>
 371      For more information about installing Boost refer to the
 372      <ulink url="&url.boost.getting.started;">getting started</ulink>
 373      pages.
 374     </para>
 375    </section>
 376
 377    <section id="installation.windows.libxslt">
 378     <title>Libxslt</title>
 379     <para>
 380      <ulink url="&url.libxslt;">Libxslt</ulink> can be downloaded
 381      for Windows from
 382      <ulink url="&url.libxml2.download.win32;">here</ulink>.
 383     </para>
 384     <para>
 385      Libxslt has other dependencies, but these can all be downloaded
 386      from the same site. Get the following package:
 387      iconv, zlib, libxml2, libxslt.
 388     </para>
 389    </section>
 390
 391    <section id="installation.windows.yaz">
 392     <title>YAZ</title>
 393     <para>
 394      <ulink url="&url.yaz;">YAZ</ulink> can be downloaded
 395      for Windows from
 396      <ulink url="&url.yaz.download.win32;">here</ulink>.
 397     </para>
 398    </section>
 399
 400    <section id="installation.windows.yazplusplus">
 401     <title>YAZ++</title>
 402     <para>
 403      Get <ulink url="&url.yazplusplus;">YAZ++</ulink> as well.
 404      Version 1.1.0 or later is required.
 405     </para>
 406     <para>
 407      YAZ++ includes NMAKE makefiles, similar to those found in the
 408      YAZ package.
 409     </para>
 410    </section>
 411
 412    <section id="installation.windows.metaproxy">
 413     <title>Metaproxy</title>
 414     <para>
 415      Metaproxy is shipped with NMAKE makefiles as well - similar
 416      to those found in the YAZ++/YAZ packages. Adjust this Makefile
 417      to point to the proper locations of Boost, Libxslt, Libxml2,
 418      zlib, iconv, yaz and yazpp.
 419     </para>
 420
 421     <variablelist>
 422      <varlistentry><term><literal>DEBUG</literal></term>
 423       <listitem><para>
 424         If set to 1, the software is
 425         compiled with debugging libraries (code generation is
 426         multi-threaded debug DLL).
 427         If set to 0, the software is compiled with release libraries
 428         (code generation is multi-threaded DLL).
 429        </para></listitem>
 430      </varlistentry>
 431
 432      <varlistentry>
 433       <term><literal>BOOST</literal></term>
 434       <listitem>
 435        <para>
 436         Boost install location
 437        </para>
 438       </listitem>
 439      </varlistentry>
 440
 441      <varlistentry>
 442       <term><literal>BOOST_VERSION</literal></term>
 443       <listitem>
 444        <para>
 445         Boost version (replace . with _).
 446        </para>
 447       </listitem>
 448      </varlistentry>
 449
 450      <varlistentry>
 451       <term><literal>BOOST_TOOLSET</literal></term>
 452       <listitem>
 453        <para>
 454         Boost toolset.
 455        </para>
 456       </listitem>
 457      </varlistentry>
 458
 459      <varlistentry>
 460       <term><literal>LIBXSLT_DIR</literal>,
 461        <literal>LIBXML2_DIR</literal> ..</term>
 462       <listitem>
 463        <para>
 464         Specify the locations of Libxslt, libiconv, libxml2 and
 465         libxslt.
 466        </para>
 467       </listitem>
 468      </varlistentry>
 469
 470     </variablelist>
 471
 472     <para>
 473      After successful compilation you'll find
 474      <literal>metaproxy.exe</literal> in the
 475      <literal>bin</literal> directory.
 476     </para>
 477    </section>
 478
 479
 480   </section>
 481  </chapter>
 482
 483 <chapter id="yazproxy-comparison">
 484  <title>YAZ Proxy Comparison</title>
 485  <para>
 486   The table below lists facilities either supported by either
 487    <ulink url="&url.yazproxy;">YAZ Proxy</ulink> or Metaproxy.
 488  </para>
 489 <table id="yazproxy-comparison-table">
 490  <title>Metaproxy / YAZ Proxy comparison</title>
 491  <tgroup cols="3">
 492   <thead>
 493    <row>
 494     <entry>Facility</entry>
 495     <entry>Metaproxy</entry>
 496     <entry>YAZ Proxy</entry>
 497    </row>
 498   </thead>
 499   <tbody>
 500    <row>
 501     <entry>Z39.50 server</entry>
 502     <entry>Using filter <literal>frontend_net</literal></entry>
 503     <entry>Supported</entry>
 504    </row>
 505    <row>
 506     <entry>SRU server</entry>
 507     <entry>Supported with filter <literal>sru_z3950</literal></entry>
 508     <entry>Supported</entry>
 509    </row>
 510    <row>
 511     <entry>Z39.50 client</entry>
 512     <entry>Supported with filter <literal>z3950_client</literal></entry>
 513     <entry>Supported</entry>
 514    </row>
 515    <row>
 516     <entry>SRU client</entry>
 517     <entry>Unsupported</entry>
 518     <entry>Unsupported</entry>
 519    </row>
 520    <row>
 521     <entry>Connection reuse</entry>
 522     <entry>Supported with filter <literal>session_shared</literal></entry>
 523     <entry>Supported</entry>
 524    </row>
 525    <row>
 526     <entry>Connection share</entry>
 527     <entry>Supported with filter <literal>session_shared</literal></entry>
 528     <entry>Unsupported</entry>
 529    </row>
 530    <row>
 531     <entry>Result set reuse</entry>
 532     <entry>Supported with filter <literal>session_shared</literal></entry>
 533     <entry>Within one Z39.50 session / HTTP keep-alive</entry>
 534    </row>
 535    <row>
 536     <entry>Record cache</entry>
 537     <entry>Supported by filter <literal>session_shared</literal></entry>
 538     <entry>Supported for last result set within one Z39.50/HTTP-keep alive session</entry>
 539    </row>
 540    <row>
 541     <entry>Z39.50 Virtual database, i.e. select any Z39.50 target for database</entry>
 542     <entry>Supported with filter <literal>virt_db</literal></entry>
 543     <entry>Unsupported</entry>
 544    </row>
 545    <row>
 546     <entry>SRU Virtual database, i.e. select any Z39.50 target for path</entry>
 547     <entry>Supported with filter <literal>virt_db</literal>,
 548      <literal>sru_z3950</literal></entry>
 549     <entry>Supported</entry>
 550    </row>
 551    <row>
 552     <entry>Multi target search</entry>
 553     <entry>Supported with filter <literal>multi</literal> (round-robin)</entry>
 554     <entry>Unsupported</entry>
 555    </row>
 556    <row>
 557     <entry>Retrieval and search limits</entry>
 558     <entry>Supported using filter <literal>limit</literal></entry>
 559     <entry>Supported</entry>
 560    </row>
 561    <row>
 562     <entry>Bandwidth limits</entry>
 563     <entry>Supported using filter <literal>limit</literal></entry>
 564     <entry>Supported</entry>
 565    </row>
 566    <row>
 567     <entry>Connect limits</entry>
 568     <entry>Supported by filter <literal>frontend_net</literal> (connect-max)</entry>
 569     <entry>Supported</entry>
 570    </row>
 571    <row>
 572     <entry>Retrieval sanity check and conversions</entry>
 573     <entry>Supported using filter <literal>record_transform</literal></entry>
 574     <entry>Supported</entry>
 575    </row>
 576    <row>
 577     <entry>Query check</entry>
 578     <entry>
 579       Supported by <literal>query_rewrite</literal> which may be check
 580       a query and throw diagnostics (errors)
 581     </entry>
 582     <entry>Supported</entry>
 583    </row>
 584    <row>
 585     <entry>Query rewrite</entry>
 586     <entry>Supported with <literal>query_rewrite</literal></entry>
 587     <entry>Unsupported</entry>
 588    </row>
 589    <row>
 590     <entry>Session invalidate for -1 hits</entry>
 591     <entry>Unsupported</entry>
 592     <entry>Supported</entry>
 593    </row>
 594    <row>
 595     <entry>Architecture</entry>
 596     <entry>Multi-threaded + select for networked modules such as
 597       <literal>frontend_net</literal>)</entry>
 598     <entry>Single-threaded using select</entry>
 599    </row>
 600
 601    <row>
 602     <entry>Extensability</entry>
 603     <entry>Most functionality implemented as loadable modules</entry>
 604     <entry>Unsupported and experimental</entry>
 605    </row>
 606
 607    <row>
 608     <entry><ulink url="&url.usemarcon;">USEMARCON</ulink></entry>
 609     <entry>Unsupported</entry>
 610     <entry>Supported</entry>
 611    </row>
 612
 613    <row>
 614     <entry>Portability</entry>
 615     <entry>
 616      Requires YAZ, YAZ++ and modern C++ compiler supporting
 617      <ulink url="&url.boost;">Boost</ulink>.
 618     </entry>
 619     <entry>
 620      Requires YAZ and YAZ++.
 621      STL is not required so pretty much any C++ compiler out there should work.
 622     </entry>
 623    </row>
 624
 625   </tbody>
 626  </tgroup>
 627 </table>
 628 </chapter>
 629
 630  <chapter id="architecture">
 631   <title>The Metaproxy Architecture</title>
 632   <para>
 633    The Metaproxy architecture is based on three concepts:
 634    the <emphasis>package</emphasis>,
 635    the <emphasis>route</emphasis>
 636    and the <emphasis>filter</emphasis>.
 637   </para>
 638   <variablelist>
 639    <varlistentry>
 640     <term>Packages</term>
 641     <listitem>
 642      <para>
 643       A package is request or response, encoded in some protocol,
 644       issued by a client, making its way through Metaproxy, send to or
 645       received from a server, or sent back to the client.
 646      </para>
 647      <para>
 648       The core of a package is the protocol unit - for example, a
 649       Z39.50 Init Request or Search Response, or an SRU searchRetrieve
 650       URL or Explain Response.  In addition to this core, a package
 651       also carries some extra information added and used by Metaproxy
 652       itself.
 653      </para>
 654      <para>
 655       In general, packages are doctored as they pass through
 656       Metaproxy.  For example, when the proxy performs authentication
 657       and authorization on a Z39.50 Init request, it removes the
 658       authentication credentials from the package so that they are not
 659       passed onto the back-end server; and when search-response
 660       packages are obtained from multiple servers, they are merged
 661       into a single unified package that makes its way back to the
 662       client.
 663      </para>
 664     </listitem>
 665    </varlistentry>
 666    <varlistentry>
 667     <term>Routes</term>
 668     <listitem>
 669      <para>
 670       Packages make their way through routes, which can be thought of
 671       as programs that operate on the package data-type.  Each
 672       incoming package initially makes its way through a default
 673       route, but may be switched to a different route based on various
 674       considerations.  Routes are made up of sequences of filters (see
 675       below).
 676      </para>
 677     </listitem>
 678    </varlistentry>
 679    <varlistentry>
 680     <term>Filters</term>
 681     <listitem>
 682      <para>
 683       Filters provide the individual instructions within a route, and
 684       effect the necessary transformations on packages.  A particular
 685       configuration of Metaproxy is essentially a set of filters,
 686       described by configuration details and arranged in order in one
 687       or more routes.  There are many kinds of filter - about a dozen
 688       at the time of writing with more appearing all the time - each
 689       performing a specific function and configured by different
 690       information.
 691      </para>
 692      <para>
 693       The word ``filter'' is sometimes used rather loosely, in two
 694       different ways: it may be used to mean a particular
 695       <emphasis>type</emphasis> of filter, as when we speak of ``the
 696       auth_simple filter'' or ``the multi filter''; or it may be used
 697       to be a specific <emphasis>instance</emphasis> of a filter
 698       within a Metaproxy configuration.  For example, a single
 699       configuration will often contain multiple instances of the
 700       <literal>z3950_client</literal> filter.  In
 701       operational terms, of these is a separate filter.  In practice,
 702       context always make it clear which sense of the word ``filter''
 703       is being used.
 704      </para>
 705      <para>
 706       Extensibility of Metaproxy is primarily through the creation of
 707       plugins that provide new filters.  The filter API is small and
 708       conceptually simple, but there are many details to master.  See
 709       the section below on
 710       <link linkend="filters">Filters</link>.
 711      </para>
 712     </listitem>
 713    </varlistentry>
 714   </variablelist>
 715   <para>
 716    Since packages are created and handled by the system itself, and
 717    routes are conceptually simple, most of the remainder of this
 718    document concentrates on filters.  After a brief overview of the
 719    filter types follows, along with some thoughts on possible future
 720    directions.
 721   </para>
 722  </chapter>
 723
 724
 725
 726  <chapter id="filters">
 727   <title>Filters</title>
 728
 729
 730   <section id="filters-introductory-notes">
 731    <title>Introductory notes</title>
 732    <para>
 733     It's useful to think of Metaproxy as an interpreter providing a small
 734     number of primitives and operations, but operating on a very
 735     complex data type, namely the ``package''.
 736    </para>
 737    <para>
 738     A package represents a Z39.50 or SRU/W request (whether for Init,
 739     Search, Scan, etc.)  together with information about where it came
 740     from.  Packages are created by front-end filters such as
 741     <literal>frontend_net</literal> (see below), which reads them from
 742     the network; other front-end filters are possible.  They then pass
 743     along a route consisting of a sequence of filters, each of which
 744     transforms the package and may also have side-effects such as
 745     generating logging.  Eventually, the route will yield a response,
 746     which is sent back to the origin.
 747    </para>
 748    <para>
 749     There are many kinds of filter: some that are defined statically
 750     as part of Metaproxy, and others may be provided by third parties
 751     and dynamically loaded.  They all conform to the same simple API
 752     of essentially two methods: <function>configure()</function> is
 753     called at startup time, and is passed an XML DOM tree representing that
 754     part of the configuration file that pertains to this filter
 755     instance: it is expected to walk that tree extracting relevant
 756     information; and <function>process()</function> is called every
 757     time the filter has to processes a package.
 758    </para>
 759    <para>
 760     While all filters provide the same API, there are different modes
 761     of functionality.  Some filters are sources: they create
 762     packages
 763     (<literal>frontend_net</literal>);
 764     others are sinks: they consume packages and return a result
 765     (<literal>backend_test</literal>,
 766     <literal>bounce</literal>,
 767     <literal>http_file</literal>,
 768     <literal>z3950_client</literal>);
 769     the others are true filters, that read, process and pass on the
 770     packages they are fed
 771     (<literal>auth_simple</literal>,
 772     <literal>log</literal>,
 773     <literal>multi</literal>,
 774     <literal>query_rewrite</literal>,
 775     <literal>record_transform</literal>,
 776     <literal>session_shared</literal>,
 777     <literal>sru_z3950</literal>,
 778     <literal>template</literal>,
 779     <literal>virt_db</literal>).
 780    </para>
 781  </section>
 782
 783
 784   <section id="overview.filter.types">
 785    <title>Overview of filter types</title>
 786    <para>
 787     We now briefly consider each of the types of filter supported by
 788     the core Metaproxy binary.  This overview is intended to give a
 789     flavor of the available functionality; more detailed information
 790     about each type of filter is included below in
 791     <xref linkend="reference"/>.
 792    </para>
 793    <para>
 794     The filters are here named by the string that is used as the
 795     <literal>type</literal> attribute of a
 796     <literal>&lt;filter&gt;</literal> element in the configuration
 797     file to request them, with the name of the class that implements
 798     them in parentheses.  (The classname is not needed for normal
 799     configuration and use of Metaproxy; it is useful only to
 800     developers.)
 801    </para>
 802    <para>
 803     The filters are here listed in alphabetical order:
 804    </para>
 805
 806 <!--
 807
 808 ### New filters:
 809
 810 New virt_db-alike that does inteligent peer choice, explain merging,
 811 adds FD&N to explain.  Keeps init responses (like "virt_db Classic"),
 812 makes routing choices based on local explain knowledge.  Ref IDDI
 813 paper.
 814
 815 Filter to convert Explain Classic to ZeeRex.
 816
 817 CQL2PQF (which needs augmented ZeeRex) - MARC for Talis.
 818
 819 SRU2Z39.50 (ditto).
 820
 821 Figure out what additional information we need in:
 822         ZeeRex (check against D3.1)
 823         Init request (e.g. loop detection)
 824         Query package (e.g. number of hops)
 825         Query response (e.g. record source)
 826
 827 -->
 828
 829    <section id="auth_simple">
 830     <title><literal>auth_simple</literal>
 831      (mp::filter::AuthSimple)</title>
 832     <para>
 833      Simple authentication and authorization.  The configuration
 834      specifies the name of a file that is the user register, which
 835      lists <varname>username</varname>:<varname>password</varname>
 836      pairs, one per line, colon separated. When a session begins, it
 837      is rejected unless username and passsword are supplied, and match
 838      a pair in the register.  The configuration file may also specific
 839      the name of another file that is the target register: this lists
 840      lists <varname>username</varname>:<varname>dbname</varname>,<varname>dbname</varname>...
 841      sets, one per line, with multiple database names separated by
 842      commas.  When a search is processed, it is rejected unless the
 843      database to be searched is one of those listed as available to
 844      the user.
 845     </para>
 846    </section>
 847
 848    <section id="backend_test">
 849     <title><literal>backend_test</literal>
 850     (mp::filter::Backend_test)</title>
 851     <para>
 852      A partial sink that provides dummy responses in the manner of the
 853      <literal>yaz-ztest</literal> Z39.50 server.  This is useful only
 854      for testing.  Seriously, you don't need this.  Pretend you didn't
 855      even read this section.
 856     </para>
 857    </section>
 858
 859    <section id="bounce">
 860     <title><literal>bounce</literal>
 861     (mp::filter::Bounce)</title>
 862     <para>
 863      A sink that swallows <emphasis>all packages</emphasis>,
 864      and returns them almost unprocessed.
 865      It never sends any package of any type further down the row, but
 866      sets Z39.50 packages to Z_Close, and HTTP_Request packages to
 867      HTTP_Response err code 400 packages, and adds a suitable bounce
 868      message.
 869      The bounce filter is usually added at end of each filter chain route
 870      to prevent infinite hanging of for example HTTP
 871      requests packages when only the Z39.50 client partial sink
 872      filter is found in the
 873      route.
 874     </para>
 875    </section>
 876
 877    <section id="cql_rpn">
 878     <title><literal>cql_rpn</literal>
 879     (mp::filter::CQLtoRPN)</title>
 880     <para>
 881      A query language transforming filter which catches Z39.50
 882      <literal>searchRequest</literal>
 883      packages containing <literal>CQL</literal> queries, transforms
 884      those to <literal>RPN</literal> queries,
 885      and sends the <literal>searchRequests</literal> on to the next
 886      filters. It is among other things useful in a SRU context.
 887     </para>
 888    </section>
 889
 890    <section id="frontend_net">
 891     <title><literal>frontend_net</literal>
 892      (mp::filter::FrontendNet)</title>
 893     <para>
 894      A source that accepts Z39.50 connections from a port
 895      specified in the configuration, reads protocol units, and
 896      feeds them into the next filter in the route.  When the result is
 897      received, it is returned to the original origin.
 898     </para>
 899    </section>
 900
 901    <section id="http_file">
 902     <title><literal>http_file</literal>
 903      (mp::filter::HttpFile)</title>
 904     <para>
 905      A partial sink which swallows only
 906      <literal>HTTP_Request</literal> packages, and
 907      returns the contents of files from the local
 908      filesystem in response to HTTP requests.
 909      It lets Z39.50 packages and all other forthcoming package types
 910      pass untouched.
 911      (Yes, Virginia, this
 912      does mean that Metaproxy is also a Web-server in its spare time.  So
 913      far it does not contain either an email-reader or a Lisp
 914      interpreter, but that day is surely coming.)
 915     </para>
 916    </section>
 917
 918    <section id="load_balance">
 919     <title><literal>load_balance</literal>
 920      (mp::filter::LoadBalance)</title>
 921     <para>
 922      Performs load balancing for incoming Z39.50 init requests.
 923      It is used together with the <literal>virt_db</literal> filter,
 924      but unlike the <literal>multi</literal> filter it does send an
 925      entire session to only one of the virtual backends. The
 926      <literal>load_balance</literal> filter is assuming that
 927      all backend targets have equal content, and chooses the backend
 928      with least load cost for a new session.
 929     <warning>
 930      <para>
 931       This filter is experimental and yet not mature for heavy load
 932       production sites.
 933      </para>
 934     </warning>
 935    </para>
 936    </section>
 937
 938    <section id="log">
 939     <title><literal>log</literal>
 940      (mp::filter::Log)</title>
 941     <para>
 942      Writes logging information to standard output, and passes on
 943      the package unchanged. A log file name can be specified, as well
 944      as multiple different logging formats.
 945    </para>
 946    </section>
 947
 948    <section id="multi">
 949    <title><literal>multi</literal>
 950      (mp::filter::Multi)</title>
 951     <para>
 952      Performs multi-database searching.
 953      See
 954      <link linkend="multidb">the extended discussion</link>
 955      of virtual databases and multi-database searching below.
 956     </para>
 957    </section>
 958
 959    <section id="query_rewrite">
 960    <title><literal>query_rewrite</literal>
 961      (mp::filter::QueryRewrite)</title>
 962     <para>
 963      Rewrites Z39.50 <literal>Type-1</literal>
 964      and <literal>Type-101</literal> (``<literal>RPN</literal>'')
 965      queries by a
 966      three-step process: the query is transliterated from Z39.50
 967      packet structures into an XML representation; that XML
 968      representation is transformed by an XSLT stylesheet; and the
 969      resulting XML is transliterated back into the Z39.50 packet
 970      structure.
 971     </para>
 972    </section>
 973
 974
 975    <section id="record_transform">
 976     <title><literal>record_transform</literal>
 977     (mp::filter::RecordTransform)</title>
 978     <para>
 979      This filter acts only on Z3950 present requests, and let all
 980      other types of packages and requests pass untouched. It's use is
 981      twofold: blocking Z3950  present requests, which the backend
 982      server does not understand and can not honor, and transforming
 983      the present syntax and elementset name according to the rules
 984      specified, to fetch only existing record formats, and transform
 985      them on the fly to requested record syntaxes.
 986     </para>
 987    </section>
 988
 989    <section id="session_shared">
 990     <title><literal>session_shared</literal>
 991      (mp::filter::SessionShared)</title>
 992     <para>
 993      This filter implements global sharing of
 994      result sets (i.e. between threads and therefore between
 995      clients), yielding performance improvements by clever resource
 996      pooling.
 997     </para>
 998    </section>
 999
1000    <section id="sru_z3950">
1001     <title><literal>sru_z3950</literal>
1002     (mp::filter::SRUtoZ3950)</title>
1003     <para>
1004      This filter transforms valid
1005      SRU GET/POST/SOAP searchRetrieve requests to Z3950 init, search,
1006      and present requests, and wraps the
1007      received hit counts and XML records into suitable SRU response
1008      messages.
1009      The <literal>sru_z3950</literal> filter  processes also  SRU
1010      GET/POST/SOAP explain requests, returning
1011      either the absolute minimum required by the standard, or a  full
1012      pre-defined ZeeReX explain record.
1013      See the
1014      <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
1015      standard pages and the
1016      <ulink url="&url.sru.explain;">SRU Explain</ulink> pages
1017      for more information on the correct explain syntax.
1018      SRU scan requests are not supported yet.
1019     </para>
1020    </section>
1021
1022    <section id="template">
1023     <title><literal>template</literal>
1024      (mp::filter::Template)</title>
1025     <para>
1026      Does nothing at all, merely passing the packet on.  (Maybe it
1027      should be called <literal>nop</literal> or
1028      <literal>passthrough</literal>?)  This exists not to be used, but
1029      to be copied - to become the skeleton of new filters as they are
1030      written.  As with <literal>backend_test</literal>, this is not
1031      intended for civilians.
1032     </para>
1033    </section>
1034
1035    <section id="virt_db">
1036     <title><literal>virt_db</literal>
1037      (mp::filter::VirtualDB)</title>
1038     <para>
1039      Performs virtual database selection: based on the name of the
1040      database in the search request, a server is selected, and its
1041      address added to the request in a <literal>VAL_PROXY</literal>
1042      otherInfo packet.  It will subsequently be used by a
1043      <literal>z3950_client</literal> filter.
1044      See
1045      <link linkend="multidb">the extended discussion</link>
1046      of virtual databases and multi-database searching below.
1047     </para>
1048    </section>
1049
1050    <section id="z3950_client">
1051     <title><literal>z3950_client</literal>
1052      (mp::filter::Z3950Client)</title>
1053     <para>
1054      A partial sink which swallows only Z39.50 packages.
1055      It performs Z39.50 searching and retrieval by proxying the
1056      packages that are passed to it.  Init requests are sent to the
1057      address specified in the <literal>VAL_PROXY</literal> otherInfo
1058      attached to the request: this may have been specified by client,
1059      or generated by a <literal>virt_db</literal> filter earlier in
1060      the route.  Subsequent requests are sent to the same address,
1061      which is remembered at Init time in a Session object.
1062      HTTP_Request packages and all other forthcoming package types
1063      are passed untouched.
1064     </para>
1065   </section>
1066
1067
1068    <section id="zeerex_explain">
1069     <title><literal>zeerex_explain</literal>
1070      (mp::filter::ZeerexExplain)</title>
1071     <para>
1072      This filter acts as a sink for
1073      Z39.50 explain requests, returning a static ZeeReX
1074      Explain XML record from the config section. All other packages
1075      are passed through.
1076      See the
1077      <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
1078      standard pages
1079      for more information on the correct explain syntax.
1080     </para>
1081     <warning>
1082      <para>
1083       This filter is not yet completed.
1084      </para>
1085     </warning>
1086    </section>
1087
1088
1089   </section>
1090
1091
1092   <section id="future.directions">
1093    <title>Future directions</title>
1094   <para>
1095     Some other filters that do not yet exist, but which would be
1096     useful, are briefly described.  These may be added in future
1097     releases (or may be created by third parties, as loadable
1098     modules).
1099    </para>
1100
1101    <variablelist>
1102     <varlistentry>
1103      <term><literal>frontend_cli</literal> (source)</term>
1104     <listitem>
1105       <para>
1106        Command-line interface for generating requests.
1107       </para>
1108      </listitem>
1109     </varlistentry>
1110     <varlistentry>
1111      <term><literal>sru_client</literal> (sink)</term>
1112      <listitem>
1113       <para>
1114        SRU/GET and SRU/SOAP searching and retrieval.
1115       </para>
1116      </listitem>
1117     </varlistentry>
1118     <varlistentry>
1119      <term><literal>opensearch_client</literal> (sink)</term>
1120      <listitem>
1121       <para>
1122        A9 OpenSearch searching and retrieval.
1123       </para>
1124      </listitem>
1125     </varlistentry>
1126    </variablelist>
1127   </section>
1128  </chapter>
1129
1130
1131
1132  <chapter id="configuration">
1133   <title>Configuration: the Metaproxy configuration file format</title>
1134
1135
1136   <section id="configuration-introductory-notes">
1137    <title>Introductory notes</title>
1138    <para>
1139     If Metaproxy is an interpreter providing operations on packages, then
1140     its configuration file can be thought of as a program for that
1141     interpreter.  Configuration is by means of a single XML file, the name
1142     of which is supplied as the sole command-line argument to the
1143     <command>metaproxy</command> program.  (See
1144     <xref linkend="reference"/> below for more information on invoking
1145     Metaproxy.)
1146    </para>
1147   </section>
1148
1149   <section id="overview.xml.structure">
1150    <title>Overview of the config file XML structure</title>
1151    <para>
1152     All elements and attributes are in the namespace
1153     <ulink url="http://indexdata.com/metaproxy"/>.
1154      This is most easily achieved by setting the default namespace on
1155      the top-level element, as here:
1156    </para>
1157    <screen>
1158     &lt;metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0"&gt;
1159    </screen>
1160    <para>
1161     The top-level element is &lt;metaproxy&gt;.  This contains
1162     a &lt;dlpath&gt; element,
1163     a &lt;start&gt; element,
1164     a &lt;filters&gt; element and
1165     a &lt;routes&gt; element, in that order.  &lt;dlpath&gt; and
1166     &lt;filters&gt; are optional; the other two are mandatory.
1167     All four are non-repeatable.
1168    </para>
1169    <para>
1170      The &lt;dlpath;&gt; element contains a text element which
1171      specifies the location of filter modules. This is only needed
1172      if Metaproxy must load 3rd party filters (most filters with Metaproxy
1173      are built into the Metaproxy application).
1174    </para>
1175   <para>
1176     The &lt;start&gt; element is empty, but carries a
1177     <literal>route</literal> attribute, whose value is the name of
1178     route at which to start running - analogous to the name of the
1179     start production in a formal grammar.
1180    </para>
1181   <para>
1182     If present, &lt;filters&gt; contains zero or more &lt;filter&gt;
1183     elements.  Each filter carries a <literal>type</literal> attribute
1184     which specifies what kind of filter is being defined
1185     (<literal>frontend_net</literal>, <literal>log</literal>, etc.)
1186     and contain various elements that provide suitable configuration
1187     for a filter of its type.  The filter-specific elements are
1188     described in
1189     <xref linkend="reference"/>.
1190     Filters defined in this part of the file must carry an
1191     <literal>id</literal> attribute so that they can be referenced
1192     from elsewhere.
1193    </para>
1194    <para>
1195     &lt;routes&gt; contains one or more &lt;route&gt; elements, each
1196     of which must carry an <literal>id</literal> element.  One of the
1197     routes must have the ID value that was specified as the start
1198     route in the &lt;start&gt; element's <literal>route</literal>
1199     attribute.  Each route contains zero or more &lt;filter&gt;
1200     elements.  These are of two types.  They may be empty, but carry a
1201     <literal>refid</literal> attribute whose value is the same as the
1202     <literal>id</literal> of a filter previously defined in the
1203     &lt;filters&gt; section.  Alternatively, a route within a filter
1204     may omit the <literal>refid</literal> attribute, but contain
1205     configuration elements similar to those used for filters defined
1206     in the &lt;filters&gt; section.  (In other words, each filter in a
1207     route may be included either by reference or by physical
1208     inclusion.)
1209    </para>
1210   </section>
1211
1212
1213   <section id="example.configuration">
1214    <title>An example configuration</title>
1215    <para>
1216     The following is a small, but complete, Metaproxy configuration
1217     file (included in the distribution as
1218     <literal>metaproxy/etc/config1.xml</literal>).
1219     This file defines a very simple configuration that simply proxies
1220     to whatever back-end server the client requests, but logs each
1221     request and response.  This can be useful for debugging complex
1222     client-server dialogues.
1223    </para>
1224    <screen><![CDATA[<?xml version="1.0"?>
1225 <metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0">
1226   <dlpath>/usr/lib/metaproxy/modules</dlpath>
1227   <start route="start"/>
1228   <filters>
1229     <filter id="frontend" type="frontend_net">
1230       <port>@:9000</port>
1231     </filter>
1232     <filter id="backend" type="z3950_client">
1233     </filter>
1234   </filters>
1235   <routes>
1236     <route id="start">
1237       <filter refid="frontend"/>
1238       <filter type="log"/>
1239       <filter refid="backend"/>
1240       <filter type="bounce"/>
1241     </route>
1242   </routes>
1243 </metaproxy>
1244 ]]></screen>
1245    <para>
1246     It works by defining a single route, called
1247     <literal>start</literal>, which consists of a sequence of four
1248     filters.  The first and last of these are included by reference:
1249     their <literal>&lt;filter&gt;</literal> elements have
1250     <literal>refid</literal> attributes that refer to filters defined
1251     within the prior <literal>&lt;filters&gt;</literal> section.  The
1252     middle filter is included inline in the route.
1253    </para>
1254    <para>
1255     The four filters in the route are as follows: first, a
1256     <literal>frontend_net</literal> filter accepts Z39.50 requests
1257     from any host on port 9000; then these requests are passed through
1258     a <literal>log</literal> filter that emits a message for each
1259     request; they are then fed into a <literal>z3950_client</literal>
1260     filter, which forwards all Z39.50 requests to the client-specified
1261     back-end Z39.509 server. Those Z39.50 packages are returned by the
1262     <literal>z3950_client</literal> filter, with the response data
1263     filled by the external Z39.50 server targeted.
1264     All non-Z39.50 packages are passed through to the
1265     <literal>bounce</literal> filter, which definitely bounces
1266     everything, including fish, bananas, cold pyjamas,
1267     mutton, beef and trout packages.
1268     When the response arrives, it is handed
1269     back to the <literal>log</literal> filter, which emits another
1270     message; and then to the <literal>frontend_net</literal> filter,
1271     which returns the response to the client.
1272    </para>
1273   </section>
1274
1275   <section id="config-file-modularity">
1276    <title>Config file modularity</title>
1277    <para>
1278     Metaproxy XML configuration snippets can be reused by other
1279     filters using the <literal>XInclude</literal> standard, as seen in
1280     the <literal>/etc/config-sru-to-z3950.xml</literal> example SRU
1281     configuration.
1282    <screen><![CDATA[
1283     <filter id="sru" type="sru_z3950">
1284       <database name="Default">
1285        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
1286                     href="explain.xml"/>
1287       </database>
1288     </filter>
1289 ]]></screen>
1290     </para>
1291   </section>
1292
1293   <section id="config-file-syntax-check">
1294    <title>Config file syntax checking</title>
1295    <para>
1296     The distribution contains RelaxNG Compact and XML syntax checking
1297     files, as well as XML Schema files. These are found in the
1298     distribution paths
1299    <screen>
1300     xml/schema/metaproxy.rnc
1301     xml/schema/metaproxy.rng
1302     xml/schema/metaproxy.xsd
1303    </screen>
1304     and can be used to verify or debug the XML structure of
1305     configuration files. For example, using the utility
1306     <filename>xmllint</filename>, syntax checking is done like this:
1307    <screen>
1308     xmllint --noout --schema xml/schema/metaproxy.xsd etc/config-local.xml
1309     xmllint --noout --relaxng xml/schema/metaproxy.rng etc/config-local.xml
1310    </screen>
1311     (A recent version of <literal>libxml2</literal> is required, as
1312     support for XML Schemas is a relatively recent addition.)
1313    </para>
1314    <para>
1315     You can of course use any other RelaxNG or XML Schema compliant tool
1316     you wish.
1317    </para>
1318    </section>
1319  </chapter>
1320
1321
1322
1323  <chapter id="multidb">
1324   <title>Virtual databases and multi-database searching</title>
1325
1326
1327   <section id="multidb-introductory-notes">
1328    <title>Introductory notes</title>
1329    <para>
1330     Two of Metaproxy's filters are concerned with multiple-database
1331     operations.  Of these, <literal>virt_db</literal> can work alone
1332     to control the routing of searches to one of a number of servers,
1333     while <literal>multi</literal> can work together with
1334     <literal>virt_db</literal> to perform multi-database searching, merging
1335     the results into a unified result-set - ``metasearch in a box''.
1336    </para>
1337    <para>
1338     The interaction between
1339     these two filters is necessarily complex: it reflects the real,
1340     irreducible complexity of multi-database searching in a protocol such
1341     as Z39.50 that separates initialization from searching, and in
1342     which the database to be searched is not known at initialization
1343     time.
1344    </para>
1345    <para>
1346     It's possible to use these filters without understanding the
1347     details of their functioning and the interaction between them; the
1348     next two sections of this chapter are ``HOW-TO'' guides for doing
1349     just that.  However, debugging complex configurations will require
1350     a deeper understanding, which the last two sections of this
1351     chapters attempt to provide.
1352    </para>
1353   </section>
1354
1355
1356   <section id="multidb.virt_db">
1357    <title>Virtual databases with the <literal>virt_db</literal> filter</title>
1358    <para>
1359     Working alone, the purpose of the
1360     <literal>virt_db</literal>
1361     filter is to route search requests to one of a selection of
1362     back-end databases.  In this way, a single Z39.50 endpoint
1363     (running Metaproxy) can provide access to several different
1364     underlying services, including those that would otherwise be
1365     inaccessible due to firewalls.  In many useful configurations, the
1366     back-end databases are local to the Metaproxy installation, but
1367     the software does not enforce this, and any valid Z39.50 servers
1368     may be used as back-ends.
1369    </para>
1370    <para>
1371     For example, a <literal>virt_db</literal>
1372     filter could be set up so that searches in the virtual database
1373     ``lc'' are forwarded to the Library of Congress bibliographic
1374     catalogue server, and searches in the virtual database ``marc''
1375     are forwarded to the toy database of MARC records that Index Data
1376     hosts for testing purposes.  A <literal>virt_db</literal>
1377     configuration to make this switch would look like this:
1378    </para>
1379    <screen><![CDATA[<filter type="virt_db">
1380   <virtual>
1381     <database>lc</database>
1382     <target>z3950.loc.gov:7090/voyager</target>
1383   </virtual>
1384   <virtual>
1385     <database>marc</database>
1386     <target>indexdata.com/marc</target>
1387   </virtual>
1388 </filter>]]></screen>
1389    <para>
1390     As well as being useful in it own right, this filter also provides
1391     the foundation for multi-database searching.
1392    </para>
1393   </section>
1394
1395
1396   <section id="multidb.multi">
1397    <title>Multi-database search with the <literal>multi</literal> filter</title>
1398    <para>
1399     To arrange for Metaproxy to broadcast searches to multiple back-end
1400     servers, the configuration needs to include two components: a
1401     <literal>virt_db</literal>
1402     filter that specifies multiple
1403     <literal>&lt;target&gt;</literal>
1404     elements, and a subsequent
1405     <literal>multi</literal>
1406     filter.  Here, for example, is a complete configuration that
1407     broadcasts searches to both the Library of Congress catalogue and
1408     Index Data's tiny testing database of MARC records:
1409    </para>
1410    <screen><![CDATA[<?xml version="1.0"?>
1411 <metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0">
1412   <start route="start"/>
1413   <routes>
1414     <route id="start">
1415       <filter type="frontend_net">
1416         <threads>10</threads>
1417         <port>@:9000</port>
1418       </filter>
1419       <filter type="virt_db">
1420         <virtual>
1421           <database>lc</database>
1422           <target>z3950.loc.gov:7090/voyager</target>
1423         </virtual>
1424         <virtual>
1425           <database>marc</database>
1426           <target>indexdata.com/marc</target>
1427         </virtual>
1428         <virtual>
1429           <database>all</database>
1430           <target>z3950.loc.gov:7090/voyager</target>
1431           <target>indexdata.com/marc</target>
1432         </virtual>
1433       </filter>
1434       <filter type="multi"/>
1435       <filter type="z3950_client">
1436         <timeout>30</timeout>
1437       </filter>
1438       <filter type="bounce"/>
1439     </route>
1440   </routes>
1441 </metaproxy>]]></screen>
1442    <para>
1443     (Using a
1444     <literal>virt_db</literal>
1445     filter that specifies multiple
1446     <literal>&lt;target&gt;</literal>
1447     elements but without a subsequent
1448     <literal>multi</literal>
1449     filter yields surprising and undesirable results, as will be
1450     described below.  Don't do that.)
1451    </para>
1452    <para>
1453     Metaproxy can be invoked with this configuration as follows:
1454    </para>
1455    <screen>../src/metaproxy --config config-simple-multi.xml</screen>
1456    <para>
1457     And thereafter, Z39.50 clients can connect to the running server
1458     (on port 9000, as specified in the configuration) and search in
1459     any of the databases
1460     <literal>lc</literal> (the Library of Congress catalogue),
1461     <literal>marc</literal> (Index Data's test database of MARC records)
1462     or
1463     <literal>all</literal> (both of these).  As an example, a session
1464     using the YAZ command-line client <literal>yaz-client</literal> is
1465     here included (edited for brevity and clarity):
1466    </para>
1467    <screen><![CDATA[$ yaz-client @:9000
1468 Connecting...OK.
1469 Z> base lc
1470 Z> find computer
1471 Search was a success.
1472 Number of hits: 10000, setno 1
1473 Elapsed: 5.521070
1474 Z> base marc
1475 Z> find computer
1476 Search was a success.
1477 Number of hits: 10, setno 3
1478 Elapsed: 0.060187
1479 Z> base all
1480 Z> find computer
1481 Search was a success.
1482 Number of hits: 10010, setno 4
1483 Elapsed: 2.237648
1484 Z> show 1
1485 [marc]Record type: USmarc
1486 001    11224466
1487 003 DLC
1488 005 00000000000000.0
1489 008 910710c19910701nju           00010 eng
1490 010    $a 11224466
1491 040    $a DLC $c DLC
1492 050 00 $a 123-xyz
1493 100 10 $a Jack Collins
1494 245 10 $a How to program a computer
1495 260 1  $a Penguin
1496 263    $a 8710
1497 300    $a p. cm.
1498 Elapsed: 0.119612
1499 Z> show 2
1500 [VOYAGER]Record type: USmarc
1501 001 13339105
1502 005 20041229102447.0
1503 008 030910s2004    caua          000 0 eng
1504 035    $a (DLC)  2003112666
1505 906    $a 7 $b cbc $c orignew $d 4 $e epcn $f 20 $g y-gencatlg
1506 925 0  $a acquire $b 1 shelf copy $x policy default
1507 955    $a pc10 2003-09-10 $a pv12 2004-06-23 to SSCD; $h sj05 2004-11-30 $e sj05 2004-11-30 to Shelf.
1508 010    $a   2003112666
1509 020    $a 0761542892
1510 040    $a DLC $c DLC $d DLC
1511 050 00 $a MLCM 2004/03312 (G)
1512 245 10 $a 007, everything or nothing : $b Prima's official strategy guide / $c created by Kaizen Media Group.
1513 246 3  $a Double-O-seven, everything or nothing
1514 246 30 $a Prima's official strategy guide
1515 260    $a Roseville, CA : $b Prima Games, $c c2004.
1516 300    $a 161 p. : $b col. ill. ; $c 28 cm.
1517 500    $a "Platforms: Nintendo GameCube, Macintosh, PC, PlayStation 2 computer entertainment system, Xbox"--P. [4] of cover.
1518 650  0 $a Video games.
1519 710 2  $a Kaizen Media Group.
1520 856 42 $3 Publisher description $u http://www.loc.gov/catdir/description/random052/2003112666.html
1521 Elapsed: 0.150623
1522 Z>
1523 ]]></screen>
1524    <para>
1525     As can be seen, the first record in the result set is from the
1526     Index Data test database, and the second from the Library of
1527     Congress database.  The result-set continues alternating records
1528     round-robin style until the point where one of the databases'
1529     records are exhausted.
1530    </para>
1531    <para>
1532     This example uses only two back-end databases; more may be used.
1533     There is no limitation imposed on the number of databases that may
1534     be metasearched in this way: issues of resource usage and
1535     administrative complexity dictate the practical limits.
1536    </para>
1537    <para>
1538     What happens when one of the databases doesn't respond?  By default,
1539     the entire multi-database search fails, and the appropriate
1540     diagnostic is returned to the client.  This is usually appropriate
1541     during development, when technicians need maximum information, but
1542     can be inconvenient in deployment, when users typically don't want
1543     to be bothered with problems of this kind and prefer just to get
1544     the records from the databases that are available.  To obtain this
1545     latter behavior add an empty
1546     <literal>&lt;hideunavailable&gt;</literal>
1547     element inside the
1548     <literal>multi</literal> filter:
1549    </para>
1550    <screen><![CDATA[      <filter type="multi">
1551         <hideunavailable/>
1552       </filter>]]></screen>
1553    <para>
1554     Under this regime, an error is reported to the client only if
1555     <emphasis>all</emphasis> the databases in a multi-database search
1556     are unavailable.
1557    </para>
1558   </section>
1559
1560
1561   <section id="multidb.what">
1562    <title>What's going on?</title>
1563    <warning>
1564     <title>Lark's vomit</title>
1565     <para>
1566      This section goes into a level of technical detail that is
1567      probably not necessary in order to configure and use Metaproxy.
1568      It is provided only for those who like to know how things work.
1569      You should feel free to skip on to the next section if this one
1570      doesn't seem like fun.
1571     </para>
1572    </warning>
1573    <para>
1574     Hold on tight - this may get a little hairy.
1575    </para>
1576    <para>
1577     In the general course of things, a Z39.50 Init request may carry
1578     with it an otherInfo packet of type <literal>VAL_PROXY</literal>,
1579     whose value indicates the address of a Z39.50 server to which the
1580     ultimate connection is to be made.  (This otherInfo packet is
1581     supported by YAZ-based Z39.50 clients and servers, but has not yet
1582     been ratified by the Maintenance Agency and so is not widely used
1583     in non-Index Data software.  We're working on it.)
1584     The <literal>VAL_PROXY</literal> packet functions
1585     analogously to the absoluteURI-style Request-URI used with the GET
1586     method when a web browser asks a proxy to forward its request: see
1587     the
1588     <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2"
1589            >Request-URI</ulink>
1590     section of
1591     <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"
1592            >the HTTP 1.1 specification</ulink>.
1593    </para>
1594    <para>
1595     Within Metaproxy, Search requests that are part of the same
1596     session as an Init request that carries a
1597     <literal>VAL_PROXY</literal> otherInfo are also annotated with the
1598     same information.  The role of the <literal>virt_db</literal>
1599     filter is to rewrite this otherInfo packet dependent on the
1600     virtual database that the client wants to search.
1601    </para>
1602    <para>
1603     When Metaproxy receives a Z39.50 Init request from a client, it
1604     doesn't immediately forward that request to the back-end server.
1605     Why not?  Because it doesn't know <emphasis>which</emphasis>
1606     back-end server to forward it to until the client sends a Search
1607     request that specifies the database that it wants to search in.
1608     Instead, it just treasures the Init request up in its heart; and,
1609     later, the first time the client does a search on one of the
1610     specified virtual databases, a connection is forged to the
1611     appropriate server and the Init request is forwarded to it.  If,
1612     later in the session, the same client searches in a different
1613     virtual database, then a connection is forged to the server that
1614     hosts it, and the same cached Init request is forwarded there,
1615     too.
1616    </para>
1617    <para>
1618     All of this clever Init-delaying is done by the
1619     <literal>frontend_net</literal> filter.  The
1620     <literal>virt_db</literal> filter knows nothing about it; in
1621     fact, because the Init request that is received from the client
1622     doesn't get forwarded until a Search request is received, the
1623     <literal>virt_db</literal> filter (and the
1624     <literal>z3950_client</literal> filter behind it) doesn't even get
1625     invoked at Init time.  The <emphasis>only</emphasis> thing that a
1626     <literal>virt_db</literal> filter ever does is rewrite the
1627     <literal>VAL_PROXY</literal> otherInfo in the requests that pass
1628     through it.
1629    </para>
1630    <para>
1631     It is possible for a <literal>virt_db</literal> filter to contain
1632     multiple
1633     <literal>&lt;target&gt;</literal>
1634     elements.  What does this mean?  Only that the filter will add
1635     multiple <literal>VAL_PROXY</literal> otherInfo packets to the
1636     Search requests that pass through it.  That's because the virtual
1637     DB filter is dumb, and does exactly what it's told - no more, no
1638     less.
1639     If a Search request with multiple <literal>VAL_PROXY</literal>
1640     otherInfo packets reaches a <literal>z3950_client</literal>
1641     filter, this is an error.  That filter doesn't know how to deal
1642     with multiple targets, so it will either just pick one and search
1643     in it, or (better) fail with an error message.
1644    </para>
1645    <para>
1646     The <literal>multi</literal> filter comes to the rescue!  This is
1647     the only filter that knows how to deal with multiple
1648     <literal>VAL_PROXY</literal> otherInfo packets, and it does so by
1649     making multiple copies of the entire Search request: one for each
1650     <literal>VAL_PROXY</literal>.  Each of these new copies is then
1651     passed down through the remaining filters in the route.  (The
1652     copies are handled in parallel though the
1653     spawning of new threads.)  Since the copies each have only one
1654     <literal>VAL_PROXY</literal> otherInfo, they can be handled by the
1655     <literal>z3950_client</literal> filter, which happily deals with
1656     each one individually.  When the results of the individual
1657     searches come back up to the <literal>multi</literal> filter, it
1658     merges them into a single Search response, which is what
1659     eventually makes it back to the client.
1660    </para>
1661   </section>
1662
1663
1664   <section id="multidb.picture">
1665    <title>A picture is worth a thousand words (but only five hundred on 64-bit architectures)</title>
1666    <simpara>
1667     <inlinemediaobject>
1668      <imageobject>
1669       <imagedata fileref="multi.pdf" format="PDF" scale="50"/>
1670      </imageobject>
1671      <imageobject>
1672       <imagedata fileref="multi.png" format="PNG"/>
1673      </imageobject>
1674      <textobject>
1675       <!-- Fall back if none of the images can be used -->
1676       <phrase>
1677        [Here there should be a diagram showing the progress of
1678        packages through the filters during a simple virtual-database
1679        search and a multi-database search, but is seems that your
1680        tool chain has not been able to include the diagram in this
1681        document.]
1682       </phrase>
1683      </textobject>
1684 <!-- ### This used to work with an older version of DocBook
1685      <caption>
1686       <para>Caption: progress of packages through filters.</para>
1687      </caption>
1688 -->
1689     </inlinemediaobject>
1690    </simpara>
1691   </section>
1692  </chapter>
1693
1694
1695  <chapter id="sru-server">
1696   <title>Combined SRU webservice and Z39.50 server configuration</title>
1697   <para>
1698    Metaproxy can act as
1699    <ulink url="&url.sru;">SRU</ulink> and
1700    web service server, which translates web service requests to
1701    <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink> packages and
1702    sends them off to common available targets.
1703   </para>
1704   <para>
1705   A typical setup for this operation needs a filter route including the
1706   following modules:
1707   </para>
1708
1709   <table id="sru-server-table-config" frame="top">
1710    <title>SRU/Z39.50 Server Filter Route Configuration</title>
1711    <tgroup cols="3">
1712     <thead>
1713      <row>
1714       <entry>Filter</entry>
1715       <entry>Importance</entry>
1716       <entry>Purpose</entry>
1717      </row>
1718     </thead>
1719
1720     <tbody>
1721      <row>
1722       <entry><literal>frontend_net</literal></entry>
1723       <entry>required</entry>
1724       <entry>Accepting HTTP connections and passing them to following
1725       filters. Since this filter also accepts Z39.50 connections, the
1726       server works as SRU and Z39.50 server on the same port.</entry>
1727      </row>
1728      <row>
1729       <entry><literal>sru_z3950</literal></entry>
1730       <entry>required</entry>
1731       <entry>Accepting SRU GET/POST/SOAP explain and
1732        searchRetrieve requests for the the configured databases.
1733        Explain requests are directly served from the static XML configuration.
1734        SearchRetrieve requests are
1735        transformed  to Z39.50 search and present packages.
1736        All other HTTP and Z39.50 packages are passed unaltered.</entry>
1737      </row>
1738      <row>
1739       <entry><literal>http_file</literal></entry>
1740       <entry>optional</entry>
1741       <entry>Serving HTTP requests from the filesystem. This is only
1742       needed if the server should serve XSLT stylesheets, static HTML
1743       files or Java Script for thin browser based clients.
1744        Z39.50 packages are passed unaltered.</entry>
1745      </row>
1746      <row>
1747       <entry><literal>cql_rpn</literal></entry>
1748       <entry>required</entry>
1749       <entry>Usually, Z39.50 servers do not talk CQL, hence the
1750       translation of the CQL query language to RPN is mandatory in
1751       most cases. Affects only  Z39.50 search packages.</entry>
1752      </row>
1753      <row>
1754       <entry><literal>record_transform</literal></entry>
1755       <entry>optional</entry>
1756       <entry>Some Z39.50 backend targets can not present XML record
1757       syntaxes in common wanted element sets. using this filter, one
1758       can transform binary MARC records to MARCXML records, and
1759       further transform those to any needed XML schema/format by XSLT
1760       transformations. Changes only  Z39.50 present packages.</entry>
1761      </row>
1762      <row>
1763       <entry><literal>session_shared</literal></entry>
1764       <entry>optional</entry>
1765       <entry>The stateless nature of web services requires frequent
1766       re-searching of the same targets for display of paged result set
1767       records. This might be an unacceptable burden for the accessed
1768       backend Z39.50 targets, and this mosule can be added for
1769       efficient backend target resource pooling.</entry>
1770      </row>
1771      <row>
1772       <entry><literal>z3950_client</literal></entry>
1773       <entry>required</entry>
1774       <entry>Finally, a Z39.50 package sink is needed in the filter
1775       chain to provide the response packages. The Z39.50 client module
1776       is used to access external targets over the network, but any
1777       coming local Z39.50 package sink could be used instead of.</entry>
1778      </row>
1779      <row>
1780       <entry><literal>bounce</literal></entry>
1781       <entry>required</entry>
1782       <entry>Any Metaproxy package arriving here did not do so by
1783       purpose, and is bounced back with connection closure. this
1784       prevents inifinite package hanging inside the SRU server.</entry>
1785      </row>
1786     </tbody>
1787    </tgroup>
1788   </table>
1789   <para>
1790    A typical minimal example <ulink url="&url.sru;">SRU</ulink>
1791    server configuration file is found in the tarball distribution at
1792    <literal>etc/config-sru-to-z3950.xml</literal>.
1793   </para>
1794   <para>
1795    Off course, any other metaproxy modules can be integrated into a
1796    SRU server solution, including, but not limited to, load balancing,
1797    multiple target querying
1798    (see  <xref linkend="multidb"/>), and complex RPN query rewrites.
1799   </para>
1800
1801
1802  </chapter>
1803
1804  <!--
1805  <chapter id="extensions">
1806   <title>Writing extensions for Metaproxy</title>
1807   <para>### To be written</para>
1808  </chapter>
1809  -->
1810
1811
1812
1813  <chapter id="classes">
1814   <title>Classes in the Metaproxy source code</title>
1815
1816
1817   <section id="classes-introductory-notes">
1818    <title>Introductory notes</title>
1819    <para>
1820     <emphasis>Stop!  Do not read this!</emphasis>
1821     You won't enjoy it at all.  You should just skip ahead to
1822     <xref linkend="reference"/>,
1823     which tells
1824     <!-- The remainder of this paragraph is lifted verbatim from
1825     Douglas Adams' _Hitch Hiker's Guide to the Galaxy_, chapter 8 -->
1826     you things you really need to know, like the fact that the
1827     fabulously beautiful planet Bethselamin is now so worried about
1828     the cumulative erosion by ten billion visiting tourists a year
1829     that any net imbalance between the amount you eat and the amount
1830     you excrete whilst on the planet is surgically removed from your
1831     bodyweight when you leave: so every time you go to the lavatory it
1832     is vitally important to get a receipt.
1833    </para>
1834    <para>
1835     This chapter contains documentation of the Metaproxy source code, and is
1836     of interest only to maintainers and developers.  If you need to
1837     change Metaproxy's behavior or write a new filter, then you will most
1838     likely find this chapter helpful.  Otherwise it's a waste of your
1839     good time.  Seriously: go and watch a film or something.
1840     <citetitle>This is Spinal Tap</citetitle> is particularly good.
1841    </para>
1842    <para>
1843     Still here?  OK, let's continue.
1844    </para>
1845    <para>
1846     In general, classes seem to be named big-endianly, so that
1847     <literal>FactoryFilter</literal> is not a filter that filters
1848     factories, but a factory that produces filters; and
1849     <literal>FactoryStatic</literal> is a factory for the statically
1850     registered filters (as opposed to those that are dynamically
1851     loaded).
1852    </para>
1853   </section>
1854
1855   <section id="individual.classes">
1856    <title>Individual classes</title>
1857    <para>
1858     The classes making up the Metaproxy application are here listed by
1859     class-name, with the names of the source files that define them in
1860     parentheses.
1861    </para>
1862
1863    <section id="class-FactoryFilter">
1864     <title><literal>mp::FactoryFilter</literal>
1865      (<filename>factory_filter.cpp</filename>)</title>
1866     <para>
1867      A factory class that exists primarily to provide the
1868      <literal>create()</literal> method, which takes the name of a
1869      filter class as its argument and returns a new filter of that
1870      type.  To enable this, the factory must first be populated by
1871      calling <literal>add_creator()</literal> for static filters (this
1872      is done by the <literal>FactoryStatic</literal> class, see below)
1873      and <literal>add_creator_dyn()</literal> for filters loaded
1874      dynamically.
1875     </para>
1876    </section>
1877
1878    <section id="class-FactoryStatic">
1879     <title><literal>mp::FactoryStatic</literal>
1880      (<filename>factory_static.cpp</filename>)</title>
1881     <para>
1882      A subclass of <literal>FactoryFilter</literal> which is
1883      responsible for registering all the statically defined filter
1884      types.  It does this by knowing about all those filters'
1885      structures, which are listed in its constructor.  Merely
1886      instantiating this class registers all the static classes.  It is
1887      for the benefit of this class that <literal>struct
1888       metaproxy_1_filter_struct</literal> exists, and that all the filter
1889      classes provide a static object of that type.
1890     </para>
1891    </section>
1892
1893    <section id="class-filter-Base">
1894     <title><literal>mp::filter::Base</literal>
1895      (<filename>filter.cpp</filename>)</title>
1896     <para>
1897      The virtual base class of all filters.  The filter API is, on the
1898      surface at least, extremely simple: two methods.
1899      <literal>configure()</literal> is passed an XML DOM tree representing
1900      that part of the configuration file that pertains to this filter
1901      instance, and is expected to walk that tree extracting relevant
1902      information.  And <literal>process()</literal> processes a
1903      package (see below).  That surface simplicity is a bit
1904      misleading, as <literal>process()</literal> needs to know a lot
1905      about the <literal>Package</literal> class in order to do
1906      anything useful.
1907     </para>
1908    </section>
1909
1910    <section id="class-AuthSimple">
1911     <title><literal>mp::filter::AuthSimple</literal>,
1912      <literal>Backend_test</literal>, etc.
1913      (<filename>filter_auth_simple.cpp</filename>,
1914      <filename>filter_backend_test.cpp</filename>, etc.)</title>
1915     <para>
1916      Individual filters.  Each of these is implemented by a header and
1917      a source file, named <filename>filter_*.hpp</filename> and
1918      <filename>filter_*.cpp</filename> respectively.  All the header
1919      files should be pretty much identical, in that they declare the
1920      class, including a private <literal>Rep</literal> class and a
1921      member pointer to it, and the two public methods.
1922     </para>
1923     <para>
1924      The source file for each filter needs to supply:
1925     </para>
1926     <itemizedlist>
1927      <listitem>
1928       <para>
1929        A definition of the private <literal>Rep</literal> class.
1930       </para>
1931      </listitem>
1932      <listitem>
1933       <para>
1934        Some boilerplate constructors and destructors.
1935       </para>
1936      </listitem>
1937      <listitem>
1938       <para>
1939        A <literal>configure()</literal> method that uses the
1940        appropriate XML fragment.
1941       </para>
1942      </listitem>
1943      <listitem>
1944       <para>
1945        Most important, the <literal>process()</literal> method that
1946        does all the actual work.
1947       </para>
1948      </listitem>
1949     </itemizedlist>
1950    </section>
1951
1952    <section id="class-Package">
1953     <title><literal>mp::Package</literal>
1954      (<filename>package.cpp</filename>)</title>
1955     <para>
1956      Represents a package on its way through the series of filters
1957      that make up a route.  This is essentially a Z39.50 or SRU APDU
1958      together with information about where it came from, which is
1959      modified as it passes through the various filters.
1960     </para>
1961    </section>
1962
1963    <section id="class-Pipe">
1964     <title><literal>mp::Pipe</literal>
1965      (<filename>pipe.cpp</filename>)</title>
1966     <para>
1967      This class provides a compatibility layer so that we have an IPC
1968      mechanism that works the same under Unix and Windows.  It's not
1969      particularly exciting.
1970     </para>
1971    </section>
1972
1973    <section id="class-RouterChain">
1974     <title><literal>mp::RouterChain</literal>
1975      (<filename>router_chain.cpp</filename>)</title>
1976     <para>
1977      ### to be written
1978     </para>
1979    </section>
1980
1981    <section id="class-RouterFleXML">
1982     <title><literal>mp::RouterFleXML</literal>
1983      (<filename>router_flexml.cpp</filename>)</title>
1984     <para>
1985      ### to be written
1986     </para>
1987    </section>
1988
1989    <section id="class-Session">
1990     <title><literal>mp::Session</literal>
1991      (<filename>session.cpp</filename>)</title>
1992     <para>
1993      ### to be written
1994     </para>
1995    </section>
1996
1997    <section id="class-ThreadPoolSocketObserver">
1998     <title><literal>mp::ThreadPoolSocketObserver</literal>
1999      (<filename>thread_pool_observer.cpp</filename>)</title>
2000     <para>
2001      ### to be written
2002     </para>
2003    </section>
2004
2005    <section id="class-util">
2006     <title><literal>mp::util</literal>
2007      (<filename>util.cpp</filename>)</title>
2008     <para>
2009      A namespace of various small utility functions and classes,
2010      collected together for convenience.  Most importantly, includes
2011      the <literal>mp::util::odr</literal> class, a wrapper for YAZ's
2012      ODR facilities.
2013     </para>
2014    </section>
2015
2016    <section id="class-xml">
2017     <title><literal>mp::xml</literal>
2018      (<filename>xmlutil.cpp</filename>)</title>
2019     <para>
2020      A namespace of various XML utility functions and classes,
2021      collected together for convenience.
2022     </para>
2023    </section>
2024   </section>
2025
2026
2027   <section id="other.source.files">
2028    <title>Other Source Files</title>
2029    <para>
2030     In addition to the Metaproxy source files that define the classes
2031     described above, there are a few additional files which are
2032     briefly described here:
2033    </para>
2034    <variablelist>
2035     <varlistentry>
2036      <term><literal>metaproxy_prog.cpp</literal></term>
2037      <listitem>
2038       <para>
2039        The main function of the <command>metaproxy</command> program.
2040       </para>
2041      </listitem>
2042     </varlistentry>
2043     <varlistentry>
2044      <term><literal>ex_router_flexml.cpp</literal></term>
2045      <listitem>
2046       <para>
2047        Identical to <literal>metaproxy_prog.cpp</literal>: it's not clear why.
2048       </para>
2049      </listitem>
2050     </varlistentry>
2051     <varlistentry>
2052      <term><literal>test_*.cpp</literal></term>
2053      <listitem>
2054       <para>
2055        Unit-tests for various modules.
2056       </para>
2057      </listitem>
2058     </varlistentry>
2059    </variablelist>
2060    <para>
2061     ### Still to be described:
2062     <literal>ex_filter_frontend_net.cpp</literal>,
2063     <literal>filter_dl.cpp</literal>,
2064     <literal>plainfile.cpp</literal>,
2065     <literal>tstdl.cpp</literal>.
2066    </para>
2067   </section>
2068  </chapter>
2069
2070
2071  <reference id="reference">
2072   <title>Reference</title>
2073    <partintro id="reference-introduction">
2074     <para>
2075      The material in this chapter is drawn directly from the individual
2076      manual entries.  In particular, the Metaproxy invocation section is
2077      available using <command>man metaproxy</command>, and the section
2078      on each individual filter is available using the name of the filter
2079      as the argument to the <command>man</command> command.
2080     </para>
2081    </partintro>
2082    &manref;
2083  </reference>
2084
2085 <appendix id="license">
2086  <title>License</title>
2087
2088   <para>
2089    Metaproxy, Copyright &copy; 1995-2009 Index Data ApS.
2090  </para>
2091
2092   <para>
2093    Metaproxy is free software; you can redistribute it and/or modify it under
2094    the terms of the GNU General Public License as published by the Free
2095    Software Foundation; either version 2, or (at your option) any later
2096    version.
2097    </para>
2098
2099   <para>
2100    Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
2101    WARRANTY; without even the implied warranty of MERCHANTABILITY or
2102    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
2103    for more details.
2104   </para>
2105
2106   <para>
2107    You should have received a copy of the GNU General Public License
2108    along with Metaproxy; see the file LICENSE.  If not, write to the
2109    Free Software Foundation,
2110    51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
2111    </para>
2112
2113  </appendix>
2114
2115  &gpl2;
2116 </book>
2117
2118  <!-- Keep this comment at the end of the file
2119  Local variables:
2120  mode: sgml
2121  sgml-omittag:t
2122  sgml-shorttag:t
2123  sgml-minimize-attributes:nil
2124  sgml-always-quote-attributes:t
2125  sgml-indent-step:1
2126  sgml-indent-data:t
2127  sgml-parent-document: nil
2128  sgml-local-catalogs: nil
2129  sgml-namecase-general:t
2130  End:
2131  -->