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 % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11      <!-- Next line allows imagedata/@format="PDF" and is taken from
  12          http://lists.oasis-open.org/archives/docbook/200303/msg00163.html
  13      -->
  14      <!ENTITY % local.notation.class "| PDF">
  15      <!-- Next line is necessary for some XML parsers, for reasons I
  16           don't understand.  I got this from
  17          http://lists.oasis-open.org/archives/docbook/200303/msg00180.html
  18      -->
  19      <!NOTATION PDF SYSTEM "PDF">
  20 ]>
  21 <!-- $Id: book.xml,v 1.63 2008-02-27 11:08:49 adam Exp $ -->
  22 <book id="metaproxy">
  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-2007</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 / 1.34.
 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    <para>
 191     Libxml2/libxslt:
 192    </para>
 193    <screen>
 194     gunzip -c libxml2-version.tar.gz|tar xf -
 195     cd libxml2-version
 196     ./configure
 197     make
 198     su
 199     make install
 200    </screen>
 201    <screen>
 202     gunzip -c libxslt-version.tar.gz|tar xf -
 203     cd libxslt-version
 204     ./configure
 205     make
 206     su
 207     make install
 208    </screen>
 209    <para>
 210     YAZ/YAZ++:
 211    </para>
 212    <screen>
 213     gunzip -c yaz-version.tar.gz|tar xf -
 214     cd yaz-version
 215     ./configure
 216     make
 217     su
 218     make install
 219    </screen>
 220    <screen>
 221     gunzip -c yazpp-version.tar.gz|tar xf -
 222     cd yazpp-version
 223     ./configure
 224     make
 225     su
 226     make install
 227    </screen>
 228    <para>
 229     Boost:
 230    </para>
 231    <screen>
 232     gunzip -c boost-version.tar.gz|tar xf -
 233     cd boost-version
 234     ./configure
 235     make
 236     su
 237     make install
 238    </screen>
 239    <para>
 240     Metaproxy:
 241    </para>
 242    <screen>
 243     gunzip -c metaproxy-version.tar.gz|tar xf -
 244     cd metaproxy-version
 245     ./configure
 246     make
 247     su
 248     make install
 249    </screen>
 250   </section>
 251
 252   <section id="installation.debian">
 253    <title>Installation on Debian GNU/Linux</title>
 254    <para>
 255     All dependencies for Metaproxy are available as
 256     <ulink url="&url.debian;">Debian</ulink>
 257     packages for the sarge (stable in 2005) and etch (testing in 2005)
 258     distributions.
 259    </para>
 260    <para>
 261     The procedures for Debian based systems, such as
 262     <ulink url="&url.ubuntu;">Ubuntu</ulink> is probably similar
 263    </para>
 264    <para>
 265     There is currently no official Debian package for YAZ++.
 266     And the official Debian package for YAZ is probably too old.
 267     But Index Data bulds "new" versions of those for Debian (i386 only).
 268    </para>
 269    <para>
 270     Update the <filename>/etc/apt/sources.list</filename>
 271     to include the Index Data repository.
 272     See YAZ' <ulink url="&url.yaz.download.debian;">Download Debian</ulink>
 273     for more information.
 274    </para>
 275    <screen>
 276     apt-get install libxslt1-dev
 277     apt-get install libyazpp2-dev
 278     apt-get install libboost-dev
 279     apt-get install libboost-thread-dev
 280     apt-get install libboost-test-dev
 281    </screen>
 282    <para>
 283     With these packages installed, the usual configure + make
 284     procedure can be used for Metaproxy as outlined in
 285     <xref linkend="installation.unix"/>.
 286    </para>
 287   </section>
 288
 289   <section id="installation.rpm">
 290    <title>Installation on RPM based Linux Systems</title>
 291    <para>
 292     All external dependencies for Metaproxy are available as
 293     RPM packages, either from your distribution site, or from the
 294     <ulink url="http://fr.rpmfind.net/">RPMfind</ulink> site.
 295    </para>
 296    <para>
 297     For example, an installation of the requires Boost C++ development
 298     libraries on RedHat Fedora C4 and C5 can be done like this:
 299     <screen>
 300     wget ftp://fr.rpmfind.net/wlinux/fedora/core/updates/testing/4/SRPMS/boost-1.33.0-3.fc4.src.rpm
 301     sudo rpmbuild --buildroot src/ --rebuild -p fc4/boost-1.33.0-3.fc4.src.rpm
 302     sudo rpm -U /usr/src/redhat/RPMS/i386/boost-*rpm
 303     </screen>
 304    </para>
 305    <para>
 306     The  <ulink url="&url.yaz;">YAZ</ulink> library is needed to
 307     compile &metaproxy;, see there
 308     for more information on available RPM packages.
 309    </para>
 310    <para>
 311     There is currently no official RPM package for YAZ++.
 312     See the <ulink url="&url.yazplusplus;">YAZ++</ulink> pages
 313     for more information on a Unix tarball install.
 314    </para>
 315    <para>
 316     With these packages installed, the usual configure + make
 317     procedure can be used for Metaproxy as outlined in
 318     <xref linkend="installation.unix"/>.
 319    </para>
 320   </section>
 321
 322   <section id="installation.windows">
 323    <title>Installation on Windows</title>
 324    <para>
 325     Metaproxy can be compiled with Microsoft
 326     <ulink url="&url.vstudio;">Visual Studio</ulink>.
 327     Version 2003 (C 7.1) and 2005 (C 8.0) is known to work.
 328    </para>
 329    <section id="installation.windows.boost">
 330     <title>Boost</title>
 331     <para>
 332      For Windows, it's easiest to get the precompiled Boost
 333      package from <ulink url="&url.boost.windows.download;">here</ulink>.
 334      Several versions of the Boost libraries may be selected when
 335      installing Boost for windows. Please choose at least the
 336      <emphasis>multithreaded</emphasis> (non-DLL) version because
 337      the Metaproxy makefile uses that.
 338     </para>
 339     <para>
 340      For more information about installing Boost refer to the
 341      <ulink url="&url.boost.getting.started;">getting started</ulink>
 342      pages.
 343     </para>
 344    </section>
 345
 346    <section id="installation.windows.libxslt">
 347     <title>Libxslt</title>
 348     <para>
 349      <ulink url="&url.libxslt;">Libxslt</ulink> can be downloaded
 350      for Windows from
 351      <ulink url="&url.libxml2.download.win32;">here</ulink>.
 352     </para>
 353     <para>
 354      Libxslt has other dependencies, but these can all be downloaded
 355      from the same site. Get the following package:
 356      iconv, zlib, libxml2, libxslt.
 357     </para>
 358    </section>
 359
 360    <section id="installation.windows.yaz">
 361     <title>YAZ</title>
 362     <para>
 363      <ulink url="&url.yaz;">YAZ</ulink> can be downloaded
 364      for Windows from
 365      <ulink url="&url.yaz.download.win32;">here</ulink>.
 366     </para>
 367    </section>
 368
 369    <section id="installation.windows.yazplusplus">
 370     <title>YAZ++</title>
 371     <para>
 372      Get <ulink url="&url.yazplusplus;">YAZ++</ulink> as well.
 373      Version 1.0.3 or later is required.
 374     </para>
 375     <para>
 376      YAZ++ includes NMAKE makefiles, similar to those found in the
 377      YAZ package.
 378     </para>
 379    </section>
 380
 381    <section id="installation.windows.metaproxy">
 382     <title>Metaproxy</title>
 383     <para>
 384      Metaproxy is shipped with NMAKE makefiles as well - similar
 385      to those found in the YAZ++/YAZ packages. Adjust this Makefile
 386      to point to the proper locations of Boost, Libxslt, Libxml2,
 387      zlib, iconv, yaz and yazpp.
 388     </para>
 389
 390     <variablelist>
 391      <varlistentry><term><literal>DEBUG</literal></term>
 392       <listitem><para>
 393         If set to 1, the software is
 394         compiled with debugging libraries (code generation is
 395         multi-threaded debug DLL).
 396         If set to 0, the software is compiled with release libraries
 397         (code generation is multi-threaded DLL).
 398        </para></listitem>
 399      </varlistentry>
 400
 401      <varlistentry>
 402       <term><literal>BOOST</literal></term>
 403       <listitem>
 404        <para>
 405         Boost install location
 406        </para>
 407       </listitem>
 408      </varlistentry>
 409
 410      <varlistentry>
 411       <term><literal>BOOST_VERSION</literal></term>
 412       <listitem>
 413        <para>
 414         Boost version (replace . with _).
 415        </para>
 416       </listitem>
 417      </varlistentry>
 418
 419      <varlistentry>
 420       <term><literal>BOOST_TOOLSET</literal></term>
 421       <listitem>
 422        <para>
 423         Boost toolset.
 424        </para>
 425       </listitem>
 426      </varlistentry>
 427
 428      <varlistentry>
 429       <term><literal>LIBXSLT_DIR</literal>,
 430        <literal>LIBXML2_DIR</literal> ..</term>
 431       <listitem>
 432        <para>
 433         Specify the locations of Libxslt, libiconv, libxml2 and
 434         libxslt.
 435        </para>
 436       </listitem>
 437      </varlistentry>
 438
 439     </variablelist>
 440
 441     <para>
 442      After successful compilation you'll find
 443      <literal>metaproxy.exe</literal> in the
 444      <literal>bin</literal> directory.
 445     </para>
 446    </section>
 447
 448
 449   </section>
 450  </chapter>
 451
 452 <chapter id="yazproxy-comparison">
 453  <title>YAZ Proxy Comparison</title>
 454  <para>
 455   The table below lists facilities either supported by either
 456    <ulink url="&url.yazproxy;">YAZ Proxy</ulink> or Metaproxy.
 457  </para>
 458 <table id="yazproxy-comparison-table">
 459  <title>Metaproxy / YAZ Proxy comparison</title>
 460  <tgroup cols="3">
 461   <thead>
 462    <row>
 463     <entry>Facility</entry>
 464     <entry>Metaproxy</entry>
 465     <entry>YAZ Proxy</entry>
 466    </row>
 467   </thead>
 468   <tbody>
 469    <row>
 470     <entry>Z39.50 server</entry>
 471     <entry>Using filter <literal>frontend_net</literal></entry>
 472     <entry>Supported</entry>
 473    </row>
 474    <row>
 475     <entry>SRU server</entry>
 476     <entry>Supported with filter <literal>sru_z3950</literal></entry>
 477     <entry>Supported</entry>
 478    </row>
 479    <row>
 480     <entry>Z39.50 client</entry>
 481     <entry>Supported with filter <literal>z3950_client</literal></entry>
 482     <entry>Supported</entry>
 483    </row>
 484    <row>
 485     <entry>SRU client</entry>
 486     <entry>Unsupported</entry>
 487     <entry>Unsupported</entry>
 488    </row>
 489    <row>
 490     <entry>Connection reuse</entry>
 491     <entry>Supported with filter <literal>session_shared</literal></entry>
 492     <entry>Supported</entry>
 493    </row>
 494    <row>
 495     <entry>Connection share</entry>
 496     <entry>Supported with filter <literal>session_shared</literal></entry>
 497     <entry>Unsupported</entry>
 498    </row>
 499    <row>
 500     <entry>Result set reuse</entry>
 501     <entry>Supported with filter <literal>session_shared</literal></entry>
 502     <entry>Within one Z39.50 session / HTTP keep-alive</entry>
 503    </row>
 504    <row>
 505     <entry>Record cache</entry>
 506     <entry>Unsupported</entry>
 507     <entry>Supported for last result set within one Z39.50/HTTP-keep alive session</entry>
 508    </row>
 509    <row>
 510     <entry>Z39.50 Virtual database, i.e. select any Z39.50 target for database</entry>
 511     <entry>Supported with filter <literal>virt_db</literal></entry>
 512     <entry>Unsupported</entry>
 513    </row>
 514    <row>
 515     <entry>SRU Virtual database, i.e. select any Z39.50 target for path</entry>
 516     <entry>Supported with filter <literal>virt_db</literal>,
 517      <literal>sru_z3950</literal></entry>
 518     <entry>Supported</entry>
 519    </row>
 520    <row>
 521     <entry>Multi target search</entry>
 522     <entry>Supported with filter <literal>multi</literal> (round-robin)</entry>
 523     <entry>Unsupported</entry>
 524    </row>
 525    <row>
 526     <entry>Retrieval and search limits</entry>
 527     <entry>Unsupported</entry>
 528     <entry>Supported</entry>
 529    </row>
 530    <row>
 531     <entry>Bandwidth limits</entry>
 532     <entry>Unsupported</entry>
 533     <entry>Supported</entry>
 534    </row>
 535    <row>
 536     <entry>Connect limits</entry>
 537     <entry>Unsupported</entry>
 538     <entry>Supported</entry>
 539    </row>
 540    <row>
 541     <entry>Retrieval sanity check and conversions</entry>
 542     <entry>Supported using filter <literal>record_transform</literal></entry>
 543     <entry>Supported</entry>
 544    </row>
 545    <row>
 546     <entry>Query check</entry>
 547     <entry>
 548      Supported in a limited way using <literal>query_rewrite</literal>
 549     </entry>
 550     <entry>Supported</entry>
 551    </row>
 552    <row>
 553     <entry>Query rewrite</entry>
 554     <entry>Supported with <literal>query_rewrite</literal></entry>
 555     <entry>Unsupported</entry>
 556    </row>
 557    <row>
 558     <entry>Session invalidate for -1 hits</entry>
 559     <entry>Unsupported</entry>
 560     <entry>Supported</entry>
 561    </row>
 562    <row>
 563     <entry>Architecture</entry>
 564     <entry>Multi-threaded + select for networked modules such as
 565       <literal>frontend_net</literal>)</entry>
 566     <entry>Single-threaded using select</entry>
 567    </row>
 568
 569    <row>
 570     <entry>Extensability</entry>
 571     <entry>Most functionality implemented as loadable modules</entry>
 572     <entry>Unsupported and experimental</entry>
 573    </row>
 574
 575    <row>
 576     <entry><ulink url="&url.usemarcon;">USEMARCON</ulink></entry>
 577     <entry>Unsupported</entry>
 578     <entry>Supported</entry>
 579    </row>
 580
 581    <row>
 582     <entry>Portability</entry>
 583     <entry>
 584      Requires YAZ, YAZ++ and modern C++ compiler supporting
 585      <ulink url="&url.boost;">Boost</ulink>.
 586     </entry>
 587     <entry>
 588      Requires YAZ and YAZ++.
 589      STL is not required so pretty much any C++ compiler out there should work.
 590     </entry>
 591    </row>
 592
 593   </tbody>
 594  </tgroup>
 595 </table>
 596 </chapter>
 597
 598  <chapter id="architecture">
 599   <title>The Metaproxy Architecture</title>
 600   <para>
 601    The Metaproxy architecture is based on three concepts:
 602    the <emphasis>package</emphasis>,
 603    the <emphasis>route</emphasis>
 604    and the <emphasis>filter</emphasis>.
 605   </para>
 606   <variablelist>
 607    <varlistentry>
 608     <term>Packages</term>
 609     <listitem>
 610      <para>
 611       A package is request or response, encoded in some protocol,
 612       issued by a client, making its way through Metaproxy, send to or
 613       received from a server, or sent back to the client.
 614      </para>
 615      <para>
 616       The core of a package is the protocol unit - for example, a
 617       Z39.50 Init Request or Search Response, or an SRU searchRetrieve
 618       URL or Explain Response.  In addition to this core, a package
 619       also carries some extra information added and used by Metaproxy
 620       itself.
 621      </para>
 622      <para>
 623       In general, packages are doctored as they pass through
 624       Metaproxy.  For example, when the proxy performs authentication
 625       and authorization on a Z39.50 Init request, it removes the
 626       authentication credentials from the package so that they are not
 627       passed onto the back-end server; and when search-response
 628       packages are obtained from multiple servers, they are merged
 629       into a single unified package that makes its way back to the
 630       client.
 631      </para>
 632     </listitem>
 633    </varlistentry>
 634    <varlistentry>
 635     <term>Routes</term>
 636     <listitem>
 637      <para>
 638       Packages make their way through routes, which can be thought of
 639       as programs that operate on the package data-type.  Each
 640       incoming package initially makes its way through a default
 641       route, but may be switched to a different route based on various
 642       considerations.  Routes are made up of sequences of filters (see
 643       below).
 644      </para>
 645     </listitem>
 646    </varlistentry>
 647    <varlistentry>
 648     <term>Filters</term>
 649     <listitem>
 650      <para>
 651       Filters provide the individual instructions within a route, and
 652       effect the necessary transformations on packages.  A particular
 653       configuration of Metaproxy is essentially a set of filters,
 654       described by configuration details and arranged in order in one
 655       or more routes.  There are many kinds of filter - about a dozen
 656       at the time of writing with more appearing all the time - each
 657       performing a specific function and configured by different
 658       information.
 659      </para>
 660      <para>
 661       The word ``filter'' is sometimes used rather loosely, in two
 662       different ways: it may be used to mean a particular
 663       <emphasis>type</emphasis> of filter, as when we speak of ``the
 664       auth_simple filter'' or ``the multi filter''; or it may be used
 665       to be a specific <emphasis>instance</emphasis> of a filter
 666       within a Metaproxy configuration.  For example, a single
 667       configuration will often contain multiple instances of the
 668       <literal>z3950_client</literal> filter.  In
 669       operational terms, of these is a separate filter.  In practice,
 670       context always make it clear which sense of the word ``filter''
 671       is being used.
 672      </para>
 673      <para>
 674       Extensibility of Metaproxy is primarily through the creation of
 675       plugins that provide new filters.  The filter API is small and
 676       conceptually simple, but there are many details to master.  See
 677       the section below on
 678       <link linkend="filters">Filters</link>.
 679      </para>
 680     </listitem>
 681    </varlistentry>
 682   </variablelist>
 683   <para>
 684    Since packages are created and handled by the system itself, and
 685    routes are conceptually simple, most of the remainder of this
 686    document concentrates on filters.  After a brief overview of the
 687    filter types follows, along with some thoughts on possible future
 688    directions.
 689   </para>
 690  </chapter>
 691
 692
 693
 694  <chapter id="filters">
 695   <title>Filters</title>
 696
 697
 698   <section id="filters-introductory-notes">
 699    <title>Introductory notes</title>
 700    <para>
 701     It's useful to think of Metaproxy as an interpreter providing a small
 702     number of primitives and operations, but operating on a very
 703     complex data type, namely the ``package''.
 704    </para>
 705    <para>
 706     A package represents a Z39.50 or SRU/W request (whether for Init,
 707     Search, Scan, etc.)  together with information about where it came
 708     from.  Packages are created by front-end filters such as
 709     <literal>frontend_net</literal> (see below), which reads them from
 710     the network; other front-end filters are possible.  They then pass
 711     along a route consisting of a sequence of filters, each of which
 712     transforms the package and may also have side-effects such as
 713     generating logging.  Eventually, the route will yield a response,
 714     which is sent back to the origin.
 715    </para>
 716    <para>
 717     There are many kinds of filter: some that are defined statically
 718     as part of Metaproxy, and others may be provided by third parties
 719     and dynamically loaded.  They all conform to the same simple API
 720     of essentially two methods: <function>configure()</function> is
 721     called at startup time, and is passed an XML DOM tree representing that
 722     part of the configuration file that pertains to this filter
 723     instance: it is expected to walk that tree extracting relevant
 724     information; and <function>process()</function> is called every
 725     time the filter has to processes a package.
 726    </para>
 727    <para>
 728     While all filters provide the same API, there are different modes
 729     of functionality.  Some filters are sources: they create
 730     packages
 731     (<literal>frontend_net</literal>);
 732     others are sinks: they consume packages and return a result
 733     (<literal>backend_test</literal>,
 734     <literal>bounce</literal>,
 735     <literal>http_file</literal>,
 736     <literal>z3950_client</literal>);
 737     the others are true filters, that read, process and pass on the
 738     packages they are fed
 739     (<literal>auth_simple</literal>,
 740     <literal>log</literal>,
 741     <literal>multi</literal>,
 742     <literal>query_rewrite</literal>,
 743     <literal>record_transform</literal>,
 744     <literal>session_shared</literal>,
 745     <literal>sru_z3950</literal>,
 746     <literal>template</literal>,
 747     <literal>virt_db</literal>).
 748    </para>
 749  </section>
 750
 751
 752   <section id="overview.filter.types">
 753    <title>Overview of filter types</title>
 754    <para>
 755     We now briefly consider each of the types of filter supported by
 756     the core Metaproxy binary.  This overview is intended to give a
 757     flavor of the available functionality; more detailed information
 758     about each type of filter is included below in
 759     <xref linkend="reference"/>.
 760    </para>
 761    <para>
 762     The filters are here named by the string that is used as the
 763     <literal>type</literal> attribute of a
 764     <literal>&lt;filter&gt;</literal> element in the configuration
 765     file to request them, with the name of the class that implements
 766     them in parentheses.  (The classname is not needed for normal
 767     configuration and use of Metaproxy; it is useful only to
 768     developers.)
 769    </para>
 770    <para>
 771     The filters are here listed in alphabetical order:
 772    </para>
 773
 774 <!--
 775
 776 ### New filters:
 777
 778 New virt_db-alike that does inteligent peer choice, explain merging,
 779 adds FD&N to explain.  Keeps init responses (like "virt_db Classic"),
 780 makes routing choices based on local explain knowledge.  Ref IDDI
 781 paper.
 782
 783 Filter to convert Explain Classic to ZeeRex.
 784
 785 CQL2PQF (which needs augmented ZeeRex) - MARC for Talis.
 786
 787 SRU2Z39.50 (ditto).
 788
 789 Figure out what additional information we need in:
 790         ZeeRex (check against D3.1)
 791         Init request (e.g. loop detection)
 792         Query package (e.g. number of hops)
 793         Query response (e.g. record source)
 794
 795 -->
 796
 797    <section id="auth_simple">
 798     <title><literal>auth_simple</literal>
 799      (mp::filter::AuthSimple)</title>
 800     <para>
 801      Simple authentication and authorization.  The configuration
 802      specifies the name of a file that is the user register, which
 803      lists <varname>username</varname>:<varname>password</varname>
 804      pairs, one per line, colon separated. When a session begins, it
 805      is rejected unless username and passsword are supplied, and match
 806      a pair in the register.  The configuration file may also specific
 807      the name of another file that is the target register: this lists
 808      lists <varname>username</varname>:<varname>dbname</varname>,<varname>dbname</varname>...
 809      sets, one per line, with multiple database names separated by
 810      commas.  When a search is processed, it is rejected unless the
 811      database to be searched is one of those listed as available to
 812      the user.
 813     </para>
 814    </section>
 815
 816    <section id="backend_test">
 817     <title><literal>backend_test</literal>
 818     (mp::filter::Backend_test)</title>
 819     <para>
 820      A partial sink that provides dummy responses in the manner of the
 821      <literal>yaz-ztest</literal> Z39.50 server.  This is useful only
 822      for testing.  Seriously, you don't need this.  Pretend you didn't
 823      even read this section.
 824     </para>
 825    </section>
 826
 827    <section id="bounce">
 828     <title><literal>bounce</literal>
 829     (mp::filter::Bounce)</title>
 830     <para>
 831      A sink that swallows <emphasis>all packages</emphasis>,
 832      and returns them almost unprocessed.
 833      It never sends any package of any type further down the row, but
 834      sets Z39.50 packages to Z_Close, and HTTP_Request packages to
 835      HTTP_Response err code 400 packages, and adds a suitable bounce
 836      message.
 837      The bounce filter is usually added at end of each filter chain route
 838      to prevent infinite hanging of for example HTTP
 839      requests packages when only the Z39.50 client partial sink
 840      filter is found in the
 841      route.
 842     </para>
 843    </section>
 844
 845    <section id="cql_rpn">
 846     <title><literal>cql_rpn</literal>
 847     (mp::filter::CQLtoRPN)</title>
 848     <para>
 849      A query language transforming filter which catches Z39.50
 850      <literal>searchRequest</literal>
 851      packages containing <literal>CQL</literal> queries, transforms
 852      those to <literal>RPN</literal> queries,
 853      and sends the <literal>searchRequests</literal> on to the next
 854      filters. It is among other things useful in a SRU context.
 855     </para>
 856    </section>
 857
 858    <section id="frontend_net">
 859     <title><literal>frontend_net</literal>
 860      (mp::filter::FrontendNet)</title>
 861     <para>
 862      A source that accepts Z39.50 connections from a port
 863      specified in the configuration, reads protocol units, and
 864      feeds them into the next filter in the route.  When the result is
 865      received, it is returned to the original origin.
 866     </para>
 867    </section>
 868
 869    <section id="http_file">
 870     <title><literal>http_file</literal>
 871      (mp::filter::HttpFile)</title>
 872     <para>
 873      A partial sink which swallows only
 874      <literal>HTTP_Request</literal> packages, and
 875      returns the contents of files from the local
 876      filesystem in response to HTTP requests.
 877      It lets Z39.50 packages and all other forthcoming package types
 878      pass untouched.
 879      (Yes, Virginia, this
 880      does mean that Metaproxy is also a Web-server in its spare time.  So
 881      far it does not contain either an email-reader or a Lisp
 882      interpreter, but that day is surely coming.)
 883     </para>
 884    </section>
 885
 886    <section id="load_balance">
 887     <title><literal>load_balance</literal>
 888      (mp::filter::LoadBalance)</title>
 889     <para>
 890      Performs load balancing for incoming Z39.50 init requests.
 891      It is used together with the <literal>virt_db</literal> filter,
 892      but unlike the <literal>multi</literal> filter it does send an
 893      entire session to only one of the virtual backends. The
 894      <literal>load_balance</literal> filter is assuming that
 895      all backend targets have equal content, and chooses the backend
 896      with least load cost for a new session.
 897     <warning>
 898      <para>
 899       This filter is experimental and yet not mature for heavy load
 900       production sites.
 901      </para>
 902     </warning>
 903    </para>
 904    </section>
 905
 906    <section id="log">
 907     <title><literal>log</literal>
 908      (mp::filter::Log)</title>
 909     <para>
 910      Writes logging information to standard output, and passes on
 911      the package unchanged. A log file name can be specified, as well
 912      as multiple different logging formats.
 913    </para>
 914    </section>
 915
 916    <section id="multi">
 917    <title><literal>multi</literal>
 918      (mp::filter::Multi)</title>
 919     <para>
 920      Performs multi-database searching.
 921      See
 922      <link linkend="multidb">the extended discussion</link>
 923      of virtual databases and multi-database searching below.
 924     </para>
 925    </section>
 926
 927    <section id="query_rewrite">
 928    <title><literal>query_rewrite</literal>
 929      (mp::filter::QueryRewrite)</title>
 930     <para>
 931      Rewrites Z39.50 <literal>Type-1</literal>
 932      and <literal>Type-101</literal> (``<literal>RPN</literal>'')
 933      queries by a
 934      three-step process: the query is transliterated from Z39.50
 935      packet structures into an XML representation; that XML
 936      representation is transformed by an XSLT stylesheet; and the
 937      resulting XML is transliterated back into the Z39.50 packet
 938      structure.
 939     </para>
 940    </section>
 941
 942
 943    <section id="record_transform">
 944     <title><literal>record_transform</literal>
 945     (mp::filter::RecordTransform)</title>
 946     <para>
 947      This filter acts only on Z3950 present requests, and let all
 948      other types of packages and requests pass untouched. It's use is
 949      twofold: blocking Z3950  present requests, which the backend
 950      server does not understand and can not honor, and transforming
 951      the present syntax and elementset name according to the rules
 952      specified, to fetch only existing record formats, and transform
 953      them on the fly to requested record syntaxes.
 954     </para>
 955    </section>
 956
 957    <section id="session_shared">
 958     <title><literal>session_shared</literal>
 959      (mp::filter::SessionShared)</title>
 960     <para>
 961      This filter implements global sharing of
 962      result sets (i.e. between threads and therefore between
 963      clients), yielding performance improvements by clever resource
 964      pooling.
 965     </para>
 966    </section>
 967
 968    <section id="sru_z3950">
 969     <title><literal>sru_z3950</literal>
 970     (mp::filter::SRUtoZ3950)</title>
 971     <para>
 972      This filter transforms valid
 973      SRU GET/POST/SOAP searchRetrieve requests to Z3950 init, search,
 974      and present requests, and wraps the
 975      received hit counts and XML records into suitable SRU response
 976      messages.
 977      The <literal>sru_z3950</literal> filter  processes also  SRU
 978      GET/POST/SOAP explain requests, returning
 979      either the absolute minimum required by the standard, or a  full
 980      pre-defined ZeeReX explain record.
 981      See the
 982      <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
 983      standard pages and the
 984      <ulink url="&url.sru.explain;">SRU Explain</ulink> pages
 985      for more information on the correct explain syntax.
 986      SRU scan requests are not supported yet.
 987     </para>
 988    </section>
 989
 990    <section id="template">
 991     <title><literal>template</literal>
 992      (mp::filter::Template)</title>
 993     <para>
 994      Does nothing at all, merely passing the packet on.  (Maybe it
 995      should be called <literal>nop</literal> or
 996      <literal>passthrough</literal>?)  This exists not to be used, but
 997      to be copied - to become the skeleton of new filters as they are
 998      written.  As with <literal>backend_test</literal>, this is not
 999      intended for civilians.
1000     </para>
1001    </section>
1002
1003    <section id="virt_db">
1004     <title><literal>virt_db</literal>
1005      (mp::filter::VirtualDB)</title>
1006     <para>
1007      Performs virtual database selection: based on the name of the
1008      database in the search request, a server is selected, and its
1009      address added to the request in a <literal>VAL_PROXY</literal>
1010      otherInfo packet.  It will subsequently be used by a
1011      <literal>z3950_client</literal> filter.
1012      See
1013      <link linkend="multidb">the extended discussion</link>
1014      of virtual databases and multi-database searching below.
1015     </para>
1016    </section>
1017
1018    <section id="z3950_client">
1019     <title><literal>z3950_client</literal>
1020      (mp::filter::Z3950Client)</title>
1021     <para>
1022      A partial sink which swallows only Z39.50 packages.
1023      It performs Z39.50 searching and retrieval by proxying the
1024      packages that are passed to it.  Init requests are sent to the
1025      address specified in the <literal>VAL_PROXY</literal> otherInfo
1026      attached to the request: this may have been specified by client,
1027      or generated by a <literal>virt_db</literal> filter earlier in
1028      the route.  Subsequent requests are sent to the same address,
1029      which is remembered at Init time in a Session object.
1030      HTTP_Request packages and all other forthcoming package types
1031      are passed untouched.
1032     </para>
1033   </section>
1034
1035
1036    <section id="zeerex_explain">
1037     <title><literal>zeerex_explain</literal>
1038      (mp::filter::ZeerexExplain)</title>
1039     <para>
1040      This filter acts as a sink for
1041      Z39.50 explain requests, returning a static ZeeReX
1042      Explain XML record from the config section. All other packages
1043      are passed through.
1044      See the
1045      <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
1046      standard pages
1047      for more information on the correct explain syntax.
1048     </para>
1049     <warning>
1050      <para>
1051       This filter is not yet completed.
1052      </para>
1053     </warning>
1054    </section>
1055
1056
1057   </section>
1058
1059
1060   <section id="future.directions">
1061    <title>Future directions</title>
1062   <para>
1063     Some other filters that do not yet exist, but which would be
1064     useful, are briefly described.  These may be added in future
1065     releases (or may be created by third parties, as loadable
1066     modules).
1067    </para>
1068
1069    <variablelist>
1070     <varlistentry>
1071      <term><literal>frontend_cli</literal> (source)</term>
1072     <listitem>
1073       <para>
1074        Command-line interface for generating requests.
1075       </para>
1076      </listitem>
1077     </varlistentry>
1078     <varlistentry>
1079      <term><literal>sru_client</literal> (sink)</term>
1080      <listitem>
1081       <para>
1082        SRU/GET and SRU/SOAP searching and retrieval.
1083       </para>
1084      </listitem>
1085     </varlistentry>
1086     <varlistentry>
1087      <term><literal>opensearch_client</literal> (sink)</term>
1088      <listitem>
1089       <para>
1090        A9 OpenSearch searching and retrieval.
1091       </para>
1092      </listitem>
1093     </varlistentry>
1094    </variablelist>
1095   </section>
1096  </chapter>
1097
1098
1099
1100  <chapter id="configuration">
1101   <title>Configuration: the Metaproxy configuration file format</title>
1102
1103
1104   <section id="configuration-introductory-notes">
1105    <title>Introductory notes</title>
1106    <para>
1107     If Metaproxy is an interpreter providing operations on packages, then
1108     its configuration file can be thought of as a program for that
1109     interpreter.  Configuration is by means of a single XML file, the name
1110     of which is supplied as the sole command-line argument to the
1111     <command>metaproxy</command> program.  (See
1112     <xref linkend="reference"/> below for more information on invoking
1113     Metaproxy.)
1114    </para>
1115   </section>
1116
1117   <section id="overview.xml.structure">
1118    <title>Overview of the config file XML structure</title>
1119    <para>
1120     All elements and attributes are in the namespace
1121     <ulink url="http://indexdata.com/metaproxy"/>.
1122      This is most easily achieved by setting the default namespace on
1123      the top-level element, as here:
1124    </para>
1125    <screen>
1126     &lt;metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0"&gt;
1127    </screen>
1128    <para>
1129     The top-level element is &lt;metaproxy&gt;.  This contains a
1130     &lt;start&gt; element, a &lt;filters&gt; element and a
1131     &lt;routes&gt; element, in that order.  &lt;filters&gt; is
1132     optional; the other two are mandatory.  All three are
1133     non-repeatable.
1134    </para>
1135   <para>
1136     The &lt;start&gt; element is empty, but carries a
1137     <literal>route</literal> attribute, whose value is the name of
1138     route at which to start running - analogous to the name of the
1139     start production in a formal grammar.
1140    </para>
1141   <para>
1142     If present, &lt;filters&gt; contains zero or more &lt;filter&gt;
1143     elements.  Each filter carries a <literal>type</literal> attribute
1144     which specifies what kind of filter is being defined
1145     (<literal>frontend_net</literal>, <literal>log</literal>, etc.)
1146     and contain various elements that provide suitable configuration
1147     for a filter of its type.  The filter-specific elements are
1148     described in
1149     <xref linkend="reference"/>.
1150     Filters defined in this part of the file must carry an
1151     <literal>id</literal> attribute so that they can be referenced
1152     from elsewhere.
1153    </para>
1154    <para>
1155     &lt;routes&gt; contains one or more &lt;route&gt; elements, each
1156     of which must carry an <literal>id</literal> element.  One of the
1157     routes must have the ID value that was specified as the start
1158     route in the &lt;start&gt; element's <literal>route</literal>
1159     attribute.  Each route contains zero or more &lt;filter&gt;
1160     elements.  These are of two types.  They may be empty, but carry a
1161     <literal>refid</literal> attribute whose value is the same as the
1162     <literal>id</literal> of a filter previously defined in the
1163     &lt;filters&gt; section.  Alternatively, a route within a filter
1164     may omit the <literal>refid</literal> attribute, but contain
1165     configuration elements similar to those used for filters defined
1166     in the &lt;filters&gt; section.  (In other words, each filter in a
1167     route may be included either by reference or by physical
1168     inclusion.)
1169    </para>
1170   </section>
1171
1172
1173   <section id="example.configuration">
1174    <title>An example configuration</title>
1175    <para>
1176     The following is a small, but complete, Metaproxy configuration
1177     file (included in the distribution as
1178     <literal>metaproxy/etc/config1.xml</literal>).
1179     This file defines a very simple configuration that simply proxies
1180     to whatever back-end server the client requests, but logs each
1181     request and response.  This can be useful for debugging complex
1182     client-server dialogues.
1183    </para>
1184    <screen><![CDATA[<?xml version="1.0"?>
1185 <metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0">
1186   <start route="start"/>
1187   <filters>
1188     <filter id="frontend" type="frontend_net">
1189       <port>@:9000</port>
1190     </filter>
1191     <filter id="backend" type="z3950_client">
1192     </filter>
1193   </filters>
1194   <routes>
1195     <route id="start">
1196       <filter refid="frontend"/>
1197       <filter type="log"/>
1198       <filter refid="backend"/>
1199       <filter type="bounce"/>
1200     </route>
1201   </routes>
1202 </metaproxy>
1203 ]]></screen>
1204    <para>
1205     It works by defining a single route, called
1206     <literal>start</literal>, which consists of a sequence of four
1207     filters.  The first and last of these are included by reference:
1208     their <literal>&lt;filter&gt;</literal> elements have
1209     <literal>refid</literal> attributes that refer to filters defined
1210     within the prior <literal>&lt;filters&gt;</literal> section.  The
1211     middle filter is included inline in the route.
1212    </para>
1213    <para>
1214     The four filters in the route are as follows: first, a
1215     <literal>frontend_net</literal> filter accepts Z39.50 requests
1216     from any host on port 9000; then these requests are passed through
1217     a <literal>log</literal> filter that emits a message for each
1218     request; they are then fed into a <literal>z3950_client</literal>
1219     filter, which forwards all Z39.50 requests to the client-specified
1220     back-end Z39.509 server. Those Z39.50 packages are returned by the
1221     <literal>z3950_client</literal> filter, with the response data
1222     filled by the external Z39.50 server targeted.
1223     All non-Z39.50 packages are passed through to the
1224     <literal>bounce</literal> filter, which definitely bounces
1225     everything, including fish, bananas, cold pyjamas,
1226     mutton, beef and trout packages.
1227     When the response arrives, it is handed
1228     back to the <literal>log</literal> filter, which emits another
1229     message; and then to the <literal>frontend_net</literal> filter,
1230     which returns the response to the client.
1231    </para>
1232   </section>
1233
1234   <section id="config-file-modularity">
1235    <title>Config file modularity</title>
1236    <para>
1237     Metaproxy XML configuration snippets can be reused by other
1238     filters using the <literal>XInclude</literal> standard, as seen in
1239     the <literal>/etc/config-sru-to-z3950.xml</literal> example SRU
1240     configuration.
1241    <screen><![CDATA[
1242     <filter id="sru" type="sru_z3950">
1243       <database name="Default">
1244        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
1245                     href="explain.xml"/>
1246       </database>
1247     </filter>
1248 ]]></screen>
1249     </para>
1250   </section>
1251
1252   <section id="config-file-syntax-check">
1253    <title>Config file syntax checking</title>
1254    <para>
1255     The distribution contains RelaxNG Compact and XML syntax checking
1256     files, as well as XML Schema files. These are found in the
1257     distribution paths
1258    <screen>
1259     xml/schema/metaproxy.rnc
1260     xml/schema/metaproxy.rng
1261     xml/schema/metaproxy.xsd
1262    </screen>
1263     and can be used to verify or debug the XML structure of
1264     configuration files. For example, using the utility
1265     <filename>xmllint</filename>, syntax checking is done like this:
1266    <screen>
1267     xmllint --noout --schema xml/schema/metaproxy.xsd etc/config-local.xml
1268     xmllint --noout --relaxng xml/schema/metaproxy.rng etc/config-local.xml
1269    </screen>
1270     (A recent version of <literal>libxml2</literal> is required, as
1271     support for XML Schemas is a relatively recent addition.)
1272    </para>
1273    <para>
1274     You can of course use any other RelaxNG or XML Schema compliant tool
1275     you wish.
1276    </para>
1277    </section>
1278  </chapter>
1279
1280
1281
1282  <chapter id="multidb">
1283   <title>Virtual databases and multi-database searching</title>
1284
1285
1286   <section id="multidb-introductory-notes">
1287    <title>Introductory notes</title>
1288    <para>
1289     Two of Metaproxy's filters are concerned with multiple-database
1290     operations.  Of these, <literal>virt_db</literal> can work alone
1291     to control the routing of searches to one of a number of servers,
1292     while <literal>multi</literal> can work together with
1293     <literal>virt_db</literal> to perform multi-database searching, merging
1294     the results into a unified result-set - ``metasearch in a box''.
1295    </para>
1296    <para>
1297     The interaction between
1298     these two filters is necessarily complex: it reflects the real,
1299     irreducible complexity of multi-database searching in a protocol such
1300     as Z39.50 that separates initialization from searching, and in
1301     which the database to be searched is not known at initialization
1302     time.
1303    </para>
1304    <para>
1305     It's possible to use these filters without understanding the
1306     details of their functioning and the interaction between them; the
1307     next two sections of this chapter are ``HOW-TO'' guides for doing
1308     just that.  However, debugging complex configurations will require
1309     a deeper understanding, which the last two sections of this
1310     chapters attempt to provide.
1311    </para>
1312   </section>
1313
1314
1315   <section id="multidb.virt_db">
1316    <title>Virtual databases with the <literal>virt_db</literal> filter</title>
1317    <para>
1318     Working alone, the purpose of the
1319     <literal>virt_db</literal>
1320     filter is to route search requests to one of a selection of
1321     back-end databases.  In this way, a single Z39.50 endpoint
1322     (running Metaproxy) can provide access to several different
1323     underlying services, including those that would otherwise be
1324     inaccessible due to firewalls.  In many useful configurations, the
1325     back-end databases are local to the Metaproxy installation, but
1326     the software does not enforce this, and any valid Z39.50 servers
1327     may be used as back-ends.
1328    </para>
1329    <para>
1330     For example, a <literal>virt_db</literal>
1331     filter could be set up so that searches in the virtual database
1332     ``lc'' are forwarded to the Library of Congress bibliographic
1333     catalogue server, and searches in the virtual database ``marc''
1334     are forwarded to the toy database of MARC records that Index Data
1335     hosts for testing purposes.  A <literal>virt_db</literal>
1336     configuration to make this switch would look like this:
1337    </para>
1338    <screen><![CDATA[<filter type="virt_db">
1339   <virtual>
1340     <database>lc</database>
1341     <target>z3950.loc.gov:7090/voyager</target>
1342   </virtual>
1343   <virtual>
1344     <database>marc</database>
1345     <target>indexdata.com/marc</target>
1346   </virtual>
1347 </filter>]]></screen>
1348    <para>
1349     As well as being useful in it own right, this filter also provides
1350     the foundation for multi-database searching.
1351    </para>
1352   </section>
1353
1354
1355   <section id="multidb.multi">
1356    <title>Multi-database search with the <literal>multi</literal> filter</title>
1357    <para>
1358     To arrange for Metaproxy to broadcast searches to multiple back-end
1359     servers, the configuration needs to include two components: a
1360     <literal>virt_db</literal>
1361     filter that specifies multiple
1362     <literal>&lt;target&gt;</literal>
1363     elements, and a subsequent
1364     <literal>multi</literal>
1365     filter.  Here, for example, is a complete configuration that
1366     broadcasts searches to both the Library of Congress catalogue and
1367     Index Data's tiny testing database of MARC records:
1368    </para>
1369    <screen><![CDATA[<?xml version="1.0"?>
1370 <metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0">
1371   <start route="start"/>
1372   <routes>
1373     <route id="start">
1374       <filter type="frontend_net">
1375         <threads>10</threads>
1376         <port>@:9000</port>
1377       </filter>
1378       <filter type="virt_db">
1379         <virtual>
1380           <database>lc</database>
1381           <target>z3950.loc.gov:7090/voyager</target>
1382         </virtual>
1383         <virtual>
1384           <database>marc</database>
1385           <target>indexdata.com/marc</target>
1386         </virtual>
1387         <virtual>
1388           <database>all</database>
1389           <target>z3950.loc.gov:7090/voyager</target>
1390           <target>indexdata.com/marc</target>
1391         </virtual>
1392       </filter>
1393       <filter type="multi"/>
1394       <filter type="z3950_client">
1395         <timeout>30</timeout>
1396       </filter>
1397       <filter type="bounce"/>
1398     </route>
1399   </routes>
1400 </metaproxy>]]></screen>
1401    <para>
1402     (Using a
1403     <literal>virt_db</literal>
1404     filter that specifies multiple
1405     <literal>&lt;target&gt;</literal>
1406     elements but without a subsequent
1407     <literal>multi</literal>
1408     filter yields surprising and undesirable results, as will be
1409     described below.  Don't do that.)
1410    </para>
1411    <para>
1412     Metaproxy can be invoked with this configuration as follows:
1413    </para>
1414    <screen>../src/metaproxy --config config-simple-multi.xml</screen>
1415    <para>
1416     And thereafter, Z39.50 clients can connect to the running server
1417     (on port 9000, as specified in the configuration) and search in
1418     any of the databases
1419     <literal>lc</literal> (the Library of Congress catalogue),
1420     <literal>marc</literal> (Index Data's test database of MARC records)
1421     or
1422     <literal>all</literal> (both of these).  As an example, a session
1423     using the YAZ command-line client <literal>yaz-client</literal> is
1424     here included (edited for brevity and clarity):
1425    </para>
1426    <screen><![CDATA[$ yaz-client @:9000
1427 Connecting...OK.
1428 Z> base lc
1429 Z> find computer
1430 Search was a success.
1431 Number of hits: 10000, setno 1
1432 Elapsed: 5.521070
1433 Z> base marc
1434 Z> find computer
1435 Search was a success.
1436 Number of hits: 10, setno 3
1437 Elapsed: 0.060187
1438 Z> base all
1439 Z> find computer
1440 Search was a success.
1441 Number of hits: 10010, setno 4
1442 Elapsed: 2.237648
1443 Z> show 1
1444 [marc]Record type: USmarc
1445 001    11224466
1446 003 DLC
1447 005 00000000000000.0
1448 008 910710c19910701nju           00010 eng
1449 010    $a 11224466
1450 040    $a DLC $c DLC
1451 050 00 $a 123-xyz
1452 100 10 $a Jack Collins
1453 245 10 $a How to program a computer
1454 260 1  $a Penguin
1455 263    $a 8710
1456 300    $a p. cm.
1457 Elapsed: 0.119612
1458 Z> show 2
1459 [VOYAGER]Record type: USmarc
1460 001 13339105
1461 005 20041229102447.0
1462 008 030910s2004    caua          000 0 eng
1463 035    $a (DLC)  2003112666
1464 906    $a 7 $b cbc $c orignew $d 4 $e epcn $f 20 $g y-gencatlg
1465 925 0  $a acquire $b 1 shelf copy $x policy default
1466 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.
1467 010    $a   2003112666
1468 020    $a 0761542892
1469 040    $a DLC $c DLC $d DLC
1470 050 00 $a MLCM 2004/03312 (G)
1471 245 10 $a 007, everything or nothing : $b Prima's official strategy guide / $c created by Kaizen Media Group.
1472 246 3  $a Double-O-seven, everything or nothing
1473 246 30 $a Prima's official strategy guide
1474 260    $a Roseville, CA : $b Prima Games, $c c2004.
1475 300    $a 161 p. : $b col. ill. ; $c 28 cm.
1476 500    $a "Platforms: Nintendo GameCube, Macintosh, PC, PlayStation 2 computer entertainment system, Xbox"--P. [4] of cover.
1477 650  0 $a Video games.
1478 710 2  $a Kaizen Media Group.
1479 856 42 $3 Publisher description $u http://www.loc.gov/catdir/description/random052/2003112666.html
1480 Elapsed: 0.150623
1481 Z>
1482 ]]></screen>
1483    <para>
1484     As can be seen, the first record in the result set is from the
1485     Index Data test database, and the second from the Library of
1486     Congress database.  The result-set continues alternating records
1487     round-robin style until the point where one of the databases'
1488     records are exhausted.
1489    </para>
1490    <para>
1491     This example uses only two back-end databases; more may be used.
1492     There is no limitation imposed on the number of databases that may
1493     be metasearched in this way: issues of resource usage and
1494     administrative complexity dictate the practical limits.
1495    </para>
1496    <para>
1497     What happens when one of the databases doesn't respond?  By default,
1498     the entire multi-database search fails, and the appropriate
1499     diagnostic is returned to the client.  This is usually appropriate
1500     during development, when technicians need maximum information, but
1501     can be inconvenient in deployment, when users typically don't want
1502     to be bothered with problems of this kind and prefer just to get
1503     the records from the databases that are available.  To obtain this
1504     latter behavior add an empty
1505     <literal>&lt;hideunavailable&gt;</literal>
1506     element inside the
1507     <literal>multi</literal> filter:
1508    </para>
1509    <screen><![CDATA[      <filter type="multi">
1510         <hideunavailable/>
1511       </filter>]]></screen>
1512    <para>
1513     Under this regime, an error is reported to the client only if
1514     <emphasis>all</emphasis> the databases in a multi-database search
1515     are unavailable.
1516    </para>
1517   </section>
1518
1519
1520   <section id="multidb.what">
1521    <title>What's going on?</title>
1522    <warning>
1523     <title>Lark's vomit</title>
1524     <para>
1525      This section goes into a level of technical detail that is
1526      probably not necessary in order to configure and use Metaproxy.
1527      It is provided only for those who like to know how things work.
1528      You should feel free to skip on to the next section if this one
1529      doesn't seem like fun.
1530     </para>
1531    </warning>
1532    <para>
1533     Hold on tight - this may get a little hairy.
1534    </para>
1535    <para>
1536     In the general course of things, a Z39.50 Init request may carry
1537     with it an otherInfo packet of type <literal>VAL_PROXY</literal>,
1538     whose value indicates the address of a Z39.50 server to which the
1539     ultimate connection is to be made.  (This otherInfo packet is
1540     supported by YAZ-based Z39.50 clients and servers, but has not yet
1541     been ratified by the Maintenance Agency and so is not widely used
1542     in non-Index Data software.  We're working on it.)
1543     The <literal>VAL_PROXY</literal> packet functions
1544     analogously to the absoluteURI-style Request-URI used with the GET
1545     method when a web browser asks a proxy to forward its request: see
1546     the
1547     <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2"
1548            >Request-URI</ulink>
1549     section of
1550     <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"
1551            >the HTTP 1.1 specification</ulink>.
1552    </para>
1553    <para>
1554     Within Metaproxy, Search requests that are part of the same
1555     session as an Init request that carries a
1556     <literal>VAL_PROXY</literal> otherInfo are also annotated with the
1557     same information.  The role of the <literal>virt_db</literal>
1558     filter is to rewrite this otherInfo packet dependent on the
1559     virtual database that the client wants to search.
1560    </para>
1561    <para>
1562     When Metaproxy receives a Z39.50 Init request from a client, it
1563     doesn't immediately forward that request to the back-end server.
1564     Why not?  Because it doesn't know <emphasis>which</emphasis>
1565     back-end server to forward it to until the client sends a Search
1566     request that specifies the database that it wants to search in.
1567     Instead, it just treasures the Init request up in its heart; and,
1568     later, the first time the client does a search on one of the
1569     specified virtual databases, a connection is forged to the
1570     appropriate server and the Init request is forwarded to it.  If,
1571     later in the session, the same client searches in a different
1572     virtual database, then a connection is forged to the server that
1573     hosts it, and the same cached Init request is forwarded there,
1574     too.
1575    </para>
1576    <para>
1577     All of this clever Init-delaying is done by the
1578     <literal>frontend_net</literal> filter.  The
1579     <literal>virt_db</literal> filter knows nothing about it; in
1580     fact, because the Init request that is received from the client
1581     doesn't get forwarded until a Search request is received, the
1582     <literal>virt_db</literal> filter (and the
1583     <literal>z3950_client</literal> filter behind it) doesn't even get
1584     invoked at Init time.  The <emphasis>only</emphasis> thing that a
1585     <literal>virt_db</literal> filter ever does is rewrite the
1586     <literal>VAL_PROXY</literal> otherInfo in the requests that pass
1587     through it.
1588    </para>
1589    <para>
1590     It is possible for a <literal>virt_db</literal> filter to contain
1591     multiple
1592     <literal>&lt;target&gt;</literal>
1593     elements.  What does this mean?  Only that the filter will add
1594     multiple <literal>VAL_PROXY</literal> otherInfo packets to the
1595     Search requests that pass through it.  That's because the virtual
1596     DB filter is dumb, and does exactly what it's told - no more, no
1597     less.
1598     If a Search request with multiple <literal>VAL_PROXY</literal>
1599     otherInfo packets reaches a <literal>z3950_client</literal>
1600     filter, this is an error.  That filter doesn't know how to deal
1601     with multiple targets, so it will either just pick one and search
1602     in it, or (better) fail with an error message.
1603    </para>
1604    <para>
1605     The <literal>multi</literal> filter comes to the rescue!  This is
1606     the only filter that knows how to deal with multiple
1607     <literal>VAL_PROXY</literal> otherInfo packets, and it does so by
1608     making multiple copies of the entire Search request: one for each
1609     <literal>VAL_PROXY</literal>.  Each of these new copies is then
1610     passed down through the remaining filters in the route.  (The
1611     copies are handled in parallel though the
1612     spawning of new threads.)  Since the copies each have only one
1613     <literal>VAL_PROXY</literal> otherInfo, they can be handled by the
1614     <literal>z3950_client</literal> filter, which happily deals with
1615     each one individually.  When the results of the individual
1616     searches come back up to the <literal>multi</literal> filter, it
1617     merges them into a single Search response, which is what
1618     eventually makes it back to the client.
1619    </para>
1620   </section>
1621
1622
1623   <section id="multidb.picture">
1624    <title>A picture is worth a thousand words (but only five hundred on 64-bit architectures)</title>
1625    <simpara>
1626     <inlinemediaobject>
1627      <imageobject>
1628       <imagedata fileref="multi.pdf" format="PDF" scale="50"/>
1629      </imageobject>
1630      <imageobject>
1631       <imagedata fileref="multi.png" format="PNG"/>
1632      </imageobject>
1633      <textobject>
1634       <!-- Fall back if none of the images can be used -->
1635       <phrase>
1636        [Here there should be a diagram showing the progress of
1637        packages through the filters during a simple virtual-database
1638        search and a multi-database search, but is seems that your
1639        tool chain has not been able to include the diagram in this
1640        document.]
1641       </phrase>
1642      </textobject>
1643 <!-- ### This used to work with an older version of DocBook
1644      <caption>
1645       <para>Caption: progress of packages through filters.</para>
1646      </caption>
1647 -->
1648     </inlinemediaobject>
1649    </simpara>
1650   </section>
1651  </chapter>
1652
1653
1654  <chapter id="sru-server">
1655   <title>Combined SRU webservice and Z39.50 server configuration</title>
1656   <para>
1657    Metaproxy can act as
1658    <ulink url="&url.sru;">SRU</ulink> and
1659    web service server, which translates web service requests to
1660    <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink> packages and
1661    sends them off to common available targets.
1662   </para>
1663   <para>
1664   A typical setup for this operation needs a filter route including the
1665   following modules:
1666   </para>
1667
1668   <table id="sru-server-table-config" frame="top">
1669    <title>SRU/Z39.50 Server Filter Route Configuration</title>
1670    <tgroup cols="3">
1671     <thead>
1672      <row>
1673       <entry>Filter</entry>
1674       <entry>Importance</entry>
1675       <entry>Purpose</entry>
1676      </row>
1677     </thead>
1678
1679     <tbody>
1680      <row>
1681       <entry><literal>frontend_net</literal></entry>
1682       <entry>required</entry>
1683       <entry>Accepting HTTP connections and passing them to following
1684       filters. Since this filter also accepts Z39.50 connections, the
1685       server works as SRU and Z39.50 server on the same port.</entry>
1686      </row>
1687      <row>
1688       <entry><literal>sru_z3950</literal></entry>
1689       <entry>required</entry>
1690       <entry>Accepting SRU GET/POST/SOAP explain and
1691        searchRetrieve requests for the the configured databases.
1692        Explain requests are directly served from the static XML configuration.
1693        SearchRetrieve requests are
1694        transformed  to Z39.50 search and present packages.
1695        All other HTTP and Z39.50 packages are passed unaltered.</entry>
1696      </row>
1697      <row>
1698       <entry><literal>http_file</literal></entry>
1699       <entry>optional</entry>
1700       <entry>Serving HTTP requests from the filesystem. This is only
1701       needed if the server should serve XSLT stylesheets, static HTML
1702       files or Java Script for thin browser based clients.
1703        Z39.50 packages are passed unaltered.</entry>
1704      </row>
1705      <row>
1706       <entry><literal>cql_rpn</literal></entry>
1707       <entry>required</entry>
1708       <entry>Usually, Z39.50 servers do not talk CQL, hence the
1709       translation of the CQL query language to RPN is mandatory in
1710       most cases. Affects only  Z39.50 search packages.</entry>
1711      </row>
1712      <row>
1713       <entry><literal>record_transform</literal></entry>
1714       <entry>optional</entry>
1715       <entry>Some Z39.50 backend targets can not present XML record
1716       syntaxes in common wanted element sets. using this filter, one
1717       can transform binary MARC records to MARCXML records, and
1718       further transform those to any needed XML schema/format by XSLT
1719       transformations. Changes only  Z39.50 present packages.</entry>
1720      </row>
1721      <row>
1722       <entry><literal>session_shared</literal></entry>
1723       <entry>optional</entry>
1724       <entry>The stateless nature of web services requires frequent
1725       re-searching of the same targets for display of paged result set
1726       records. This might be an unacceptable burden for the accessed
1727       backend Z39.50 targets, and this mosule can be added for
1728       efficient backend target resource pooling.</entry>
1729      </row>
1730      <row>
1731       <entry><literal>z3950_client</literal></entry>
1732       <entry>required</entry>
1733       <entry>Finally, a Z39.50 package sink is needed in the filter
1734       chain to provide the response packages. The Z39.50 client module
1735       is used to access external targets over the network, but any
1736       coming local Z39.50 package sink could be used instead of.</entry>
1737      </row>
1738      <row>
1739       <entry><literal>bounce</literal></entry>
1740       <entry>required</entry>
1741       <entry>Any Metaproxy package arriving here did not do so by
1742       purpose, and is bounced back with connection closure. this
1743       prevents inifinite package hanging inside the SRU server.</entry>
1744      </row>
1745     </tbody>
1746    </tgroup>
1747   </table>
1748   <para>
1749    A typical minimal example <ulink url="&url.sru;">SRU</ulink>
1750    server configuration file is found in the tarball distribution at
1751    <literal>etc/config-sru-to-z3950.xml</literal>.
1752   </para>
1753   <para>
1754    Off course, any other metaproxy modules can be integrated into a
1755    SRU server solution, including, but not limited to, load balancing,
1756    multiple target querying
1757    (see  <xref linkend="multidb"/>), and complex RPN query rewrites.
1758   </para>
1759
1760
1761  </chapter>
1762
1763  <!--
1764  <chapter id="extensions">
1765   <title>Writing extensions for Metaproxy</title>
1766   <para>### To be written</para>
1767  </chapter>
1768  -->
1769
1770
1771
1772  <chapter id="classes">
1773   <title>Classes in the Metaproxy source code</title>
1774
1775
1776   <section id="classes-introductory-notes">
1777    <title>Introductory notes</title>
1778    <para>
1779     <emphasis>Stop!  Do not read this!</emphasis>
1780     You won't enjoy it at all.  You should just skip ahead to
1781     <xref linkend="reference"/>,
1782     which tells
1783     <!-- The remainder of this paragraph is lifted verbatim from
1784     Douglas Adams' _Hitch Hiker's Guide to the Galaxy_, chapter 8 -->
1785     you things you really need to know, like the fact that the
1786     fabulously beautiful planet Bethselamin is now so worried about
1787     the cumulative erosion by ten billion visiting tourists a year
1788     that any net imbalance between the amount you eat and the amount
1789     you excrete whilst on the planet is surgically removed from your
1790     bodyweight when you leave: so every time you go to the lavatory it
1791     is vitally important to get a receipt.
1792    </para>
1793    <para>
1794     This chapter contains documentation of the Metaproxy source code, and is
1795     of interest only to maintainers and developers.  If you need to
1796     change Metaproxy's behavior or write a new filter, then you will most
1797     likely find this chapter helpful.  Otherwise it's a waste of your
1798     good time.  Seriously: go and watch a film or something.
1799     <citetitle>This is Spinal Tap</citetitle> is particularly good.
1800    </para>
1801    <para>
1802     Still here?  OK, let's continue.
1803    </para>
1804    <para>
1805     In general, classes seem to be named big-endianly, so that
1806     <literal>FactoryFilter</literal> is not a filter that filters
1807     factories, but a factory that produces filters; and
1808     <literal>FactoryStatic</literal> is a factory for the statically
1809     registered filters (as opposed to those that are dynamically
1810     loaded).
1811    </para>
1812   </section>
1813
1814   <section id="individual.classes">
1815    <title>Individual classes</title>
1816    <para>
1817     The classes making up the Metaproxy application are here listed by
1818     class-name, with the names of the source files that define them in
1819     parentheses.
1820    </para>
1821
1822    <section id="class-FactoryFilter">
1823     <title><literal>mp::FactoryFilter</literal>
1824      (<filename>factory_filter.cpp</filename>)</title>
1825     <para>
1826      A factory class that exists primarily to provide the
1827      <literal>create()</literal> method, which takes the name of a
1828      filter class as its argument and returns a new filter of that
1829      type.  To enable this, the factory must first be populated by
1830      calling <literal>add_creator()</literal> for static filters (this
1831      is done by the <literal>FactoryStatic</literal> class, see below)
1832      and <literal>add_creator_dyn()</literal> for filters loaded
1833      dynamically.
1834     </para>
1835    </section>
1836
1837    <section id="class-FactoryStatic">
1838     <title><literal>mp::FactoryStatic</literal>
1839      (<filename>factory_static.cpp</filename>)</title>
1840     <para>
1841      A subclass of <literal>FactoryFilter</literal> which is
1842      responsible for registering all the statically defined filter
1843      types.  It does this by knowing about all those filters'
1844      structures, which are listed in its constructor.  Merely
1845      instantiating this class registers all the static classes.  It is
1846      for the benefit of this class that <literal>struct
1847       metaproxy_1_filter_struct</literal> exists, and that all the filter
1848      classes provide a static object of that type.
1849     </para>
1850    </section>
1851
1852    <section id="class-filter-Base">
1853     <title><literal>mp::filter::Base</literal>
1854      (<filename>filter.cpp</filename>)</title>
1855     <para>
1856      The virtual base class of all filters.  The filter API is, on the
1857      surface at least, extremely simple: two methods.
1858      <literal>configure()</literal> is passed an XML DOM tree representing
1859      that part of the configuration file that pertains to this filter
1860      instance, and is expected to walk that tree extracting relevant
1861      information.  And <literal>process()</literal> processes a
1862      package (see below).  That surface simplicity is a bit
1863      misleading, as <literal>process()</literal> needs to know a lot
1864      about the <literal>Package</literal> class in order to do
1865      anything useful.
1866     </para>
1867    </section>
1868
1869    <section id="class-AuthSimple">
1870     <title><literal>mp::filter::AuthSimple</literal>,
1871      <literal>Backend_test</literal>, etc.
1872      (<filename>filter_auth_simple.cpp</filename>,
1873      <filename>filter_backend_test.cpp</filename>, etc.)</title>
1874     <para>
1875      Individual filters.  Each of these is implemented by a header and
1876      a source file, named <filename>filter_*.hpp</filename> and
1877      <filename>filter_*.cpp</filename> respectively.  All the header
1878      files should be pretty much identical, in that they declare the
1879      class, including a private <literal>Rep</literal> class and a
1880      member pointer to it, and the two public methods.
1881     </para>
1882     <para>
1883      The source file for each filter needs to supply:
1884     </para>
1885     <itemizedlist>
1886      <listitem>
1887       <para>
1888        A definition of the private <literal>Rep</literal> class.
1889       </para>
1890      </listitem>
1891      <listitem>
1892       <para>
1893        Some boilerplate constructors and destructors.
1894       </para>
1895      </listitem>
1896      <listitem>
1897       <para>
1898        A <literal>configure()</literal> method that uses the
1899        appropriate XML fragment.
1900       </para>
1901      </listitem>
1902      <listitem>
1903       <para>
1904        Most important, the <literal>process()</literal> method that
1905        does all the actual work.
1906       </para>
1907      </listitem>
1908     </itemizedlist>
1909    </section>
1910
1911    <section id="class-Package">
1912     <title><literal>mp::Package</literal>
1913      (<filename>package.cpp</filename>)</title>
1914     <para>
1915      Represents a package on its way through the series of filters
1916      that make up a route.  This is essentially a Z39.50 or SRU APDU
1917      together with information about where it came from, which is
1918      modified as it passes through the various filters.
1919     </para>
1920    </section>
1921
1922    <section id="class-Pipe">
1923     <title><literal>mp::Pipe</literal>
1924      (<filename>pipe.cpp</filename>)</title>
1925     <para>
1926      This class provides a compatibility layer so that we have an IPC
1927      mechanism that works the same under Unix and Windows.  It's not
1928      particularly exciting.
1929     </para>
1930    </section>
1931
1932    <section id="class-RouterChain">
1933     <title><literal>mp::RouterChain</literal>
1934      (<filename>router_chain.cpp</filename>)</title>
1935     <para>
1936      ### to be written
1937     </para>
1938    </section>
1939
1940    <section id="class-RouterFleXML">
1941     <title><literal>mp::RouterFleXML</literal>
1942      (<filename>router_flexml.cpp</filename>)</title>
1943     <para>
1944      ### to be written
1945     </para>
1946    </section>
1947
1948    <section id="class-Session">
1949     <title><literal>mp::Session</literal>
1950      (<filename>session.cpp</filename>)</title>
1951     <para>
1952      ### to be written
1953     </para>
1954    </section>
1955
1956    <section id="class-ThreadPoolSocketObserver">
1957     <title><literal>mp::ThreadPoolSocketObserver</literal>
1958      (<filename>thread_pool_observer.cpp</filename>)</title>
1959     <para>
1960      ### to be written
1961     </para>
1962    </section>
1963
1964    <section id="class-util">
1965     <title><literal>mp::util</literal>
1966      (<filename>util.cpp</filename>)</title>
1967     <para>
1968      A namespace of various small utility functions and classes,
1969      collected together for convenience.  Most importantly, includes
1970      the <literal>mp::util::odr</literal> class, a wrapper for YAZ's
1971      ODR facilities.
1972     </para>
1973    </section>
1974
1975    <section id="class-xml">
1976     <title><literal>mp::xml</literal>
1977      (<filename>xmlutil.cpp</filename>)</title>
1978     <para>
1979      A namespace of various XML utility functions and classes,
1980      collected together for convenience.
1981     </para>
1982    </section>
1983   </section>
1984
1985
1986   <section id="other.source.files">
1987    <title>Other Source Files</title>
1988    <para>
1989     In addition to the Metaproxy source files that define the classes
1990     described above, there are a few additional files which are
1991     briefly described here:
1992    </para>
1993    <variablelist>
1994     <varlistentry>
1995      <term><literal>metaproxy_prog.cpp</literal></term>
1996      <listitem>
1997       <para>
1998        The main function of the <command>metaproxy</command> program.
1999       </para>
2000      </listitem>
2001     </varlistentry>
2002     <varlistentry>
2003      <term><literal>ex_router_flexml.cpp</literal></term>
2004      <listitem>
2005       <para>
2006        Identical to <literal>metaproxy_prog.cpp</literal>: it's not clear why.
2007       </para>
2008      </listitem>
2009     </varlistentry>
2010     <varlistentry>
2011      <term><literal>test_*.cpp</literal></term>
2012      <listitem>
2013       <para>
2014        Unit-tests for various modules.
2015       </para>
2016      </listitem>
2017     </varlistentry>
2018    </variablelist>
2019    <para>
2020     ### Still to be described:
2021     <literal>ex_filter_frontend_net.cpp</literal>,
2022     <literal>filter_dl.cpp</literal>,
2023     <literal>plainfile.cpp</literal>,
2024     <literal>tstdl.cpp</literal>.
2025    </para>
2026   </section>
2027  </chapter>
2028
2029
2030  <reference id="reference">
2031   <title>Reference</title>
2032    <partintro id="reference-introduction">
2033     <para>
2034      The material in this chapter is drawn directly from the individual
2035      manual entries.  In particular, the Metaproxy invocation section is
2036      available using <command>man metaproxy</command>, and the section
2037      on each individual filter is available using the name of the filter
2038      as the argument to the <command>man</command> command.
2039     </para>
2040    </partintro>
2041    &manref;
2042  </reference>
2043
2044 <appendix id="license">
2045  <title>License</title>
2046
2047   <para>
2048    Metaproxy, Copyright &copy; 1995-2007 Index Data ApS.
2049  </para>
2050
2051   <para>
2052    Metaproxy is free software; you can redistribute it and/or modify it under
2053    the terms of the GNU General Public License as published by the Free
2054    Software Foundation; either version 2, or (at your option) any later
2055    version.
2056    </para>
2057
2058   <para>
2059    Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
2060    WARRANTY; without even the implied warranty of MERCHANTABILITY or
2061    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
2062    for more details.
2063   </para>
2064
2065   <para>
2066    You should have received a copy of the GNU General Public License
2067    along with Metaproxy; see the file LICENSE.  If not, write to the
2068    Free Software Foundation,
2069    51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
2070    </para>
2071
2072   <sect1 id="gpl">
2073    <title>GNU General Public License</title>
2074    <screen>
2075                     GNU GENERAL PUBLIC LICENSE
2076                        Version 2, June 1991
2077
2078  Copyright (C) 1989, 1991 Free Software Foundation, Inc.
2079                        51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
2080 w Everyone is permitted to copy and distribute verbatim copies
2081  of this license document, but changing it is not allowed.
2082
2083                             Preamble
2084
2085   The licenses for most software are designed to take away your
2086 freedom to share and change it.  By contrast, the GNU General Public
2087 License is intended to guarantee your freedom to share and change free
2088 software--to make sure the software is free for all its users.  This
2089 General Public License applies to most of the Free Software
2090 Foundation's software and to any other program whose authors commit to
2091 using it.  (Some other Free Software Foundation software is covered by
2092 the GNU Library General Public License instead.)  You can apply it to
2093 your programs, too.
2094
2095   When we speak of free software, we are referring to freedom, not
2096 price.  Our General Public Licenses are designed to make sure that you
2097 have the freedom to distribute copies of free software (and charge for
2098 this service if you wish), that you receive source code or can get it
2099 if you want it, that you can change the software or use pieces of it
2100 in new free programs; and that you know you can do these things.
2101
2102   To protect your rights, we need to make restrictions that forbid
2103 anyone to deny you these rights or to ask you to surrender the rights.
2104 These restrictions translate to certain responsibilities for you if you
2105 distribute copies of the software, or if you modify it.
2106
2107   For example, if you distribute copies of such a program, whether
2108 gratis or for a fee, you must give the recipients all the rights that
2109 you have.  You must make sure that they, too, receive or can get the
2110 source code.  And you must show them these terms so they know their
2111 rights.
2112
2113   We protect your rights with two steps: (1) copyright the software, and
2114 (2) offer you this license which gives you legal permission to copy,
2115 distribute and/or modify the software.
2116
2117   Also, for each author's protection and ours, we want to make certain
2118 that everyone understands that there is no warranty for this free
2119 software.  If the software is modified by someone else and passed on, we
2120 want its recipients to know that what they have is not the original, so
2121 that any problems introduced by others will not reflect on the original
2122 authors' reputations.
2123
2124   Finally, any free program is threatened constantly by software
2125 patents.  We wish to avoid the danger that redistributors of a free
2126 program will individually obtain patent licenses, in effect making the
2127 program proprietary.  To prevent this, we have made it clear that any
2128 patent must be licensed for everyone's free use or not licensed at all.
2129
2130   The precise terms and conditions for copying, distribution and
2131 modification follow.
2132
2133                     GNU GENERAL PUBLIC LICENSE
2134    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2135
2136   0. This License applies to any program or other work which contains
2137 a notice placed by the copyright holder saying it may be distributed
2138 under the terms of this General Public License.  The "Program", below,
2139 refers to any such program or work, and a "work based on the Program"
2140 means either the Program or any derivative work under copyright law:
2141 that is to say, a work containing the Program or a portion of it,
2142 either verbatim or with modifications and/or translated into another
2143 language.  (Hereinafter, translation is included without limitation in
2144 the term "modification".)  Each licensee is addressed as "you".
2145
2146 Activities other than copying, distribution and modification are not
2147 covered by this License; they are outside its scope.  The act of
2148 running the Program is not restricted, and the output from the Program
2149 is covered only if its contents constitute a work based on the
2150 Program (independent of having been made by running the Program).
2151 Whether that is true depends on what the Program does.
2152
2153   1. You may copy and distribute verbatim copies of the Program's
2154 source code as you receive it, in any medium, provided that you
2155 conspicuously and appropriately publish on each copy an appropriate
2156 copyright notice and disclaimer of warranty; keep intact all the
2157 notices that refer to this License and to the absence of any warranty;
2158 and give any other recipients of the Program a copy of this License
2159 along with the Program.
2160
2161 You may charge a fee for the physical act of transferring a copy, and
2162 you may at your option offer warranty protection in exchange for a fee.
2163
2164   2. You may modify your copy or copies of the Program or any portion
2165 of it, thus forming a work based on the Program, and copy and
2166 distribute such modifications or work under the terms of Section 1
2167 above, provided that you also meet all of these conditions:
2168
2169     a) You must cause the modified files to carry prominent notices
2170     stating that you changed the files and the date of any change.
2171
2172     b) You must cause any work that you distribute or publish, that in
2173     whole or in part contains or is derived from the Program or any
2174     part thereof, to be licensed as a whole at no charge to all third
2175     parties under the terms of this License.
2176
2177     c) If the modified program normally reads commands interactively
2178     when run, you must cause it, when started running for such
2179     interactive use in the most ordinary way, to print or display an
2180     announcement including an appropriate copyright notice and a
2181     notice that there is no warranty (or else, saying that you provide
2182     a warranty) and that users may redistribute the program under
2183     these conditions, and telling the user how to view a copy of this
2184     License.  (Exception: if the Program itself is interactive but
2185     does not normally print such an announcement, your work based on
2186     the Program is not required to print an announcement.)
2187
2188 These requirements apply to the modified work as a whole.  If
2189 identifiable sections of that work are not derived from the Program,
2190 and can be reasonably considered independent and separate works in
2191 themselves, then this License, and its terms, do not apply to those
2192 sections when you distribute them as separate works.  But when you
2193 distribute the same sections as part of a whole which is a work based
2194 on the Program, the distribution of the whole must be on the terms of
2195 this License, whose permissions for other licensees extend to the
2196 entire whole, and thus to each and every part regardless of who wrote it.
2197
2198 Thus, it is not the intent of this section to claim rights or contest
2199 your rights to work written entirely by you; rather, the intent is to
2200 exercise the right to control the distribution of derivative or
2201 collective works based on the Program.
2202
2203 In addition, mere aggregation of another work not based on the Program
2204 with the Program (or with a work based on the Program) on a volume of
2205 a storage or distribution medium does not bring the other work under
2206 the scope of this License.
2207
2208   3. You may copy and distribute the Program (or a work based on it,
2209 under Section 2) in object code or executable form under the terms of
2210 Sections 1 and 2 above provided that you also do one of the following:
2211
2212     a) Accompany it with the complete corresponding machine-readable
2213     source code, which must be distributed under the terms of Sections
2214     1 and 2 above on a medium customarily used for software interchange; or,
2215
2216     b) Accompany it with a written offer, valid for at least three
2217     years, to give any third party, for a charge no more than your
2218     cost of physically performing source distribution, a complete
2219     machine-readable copy of the corresponding source code, to be
2220     distributed under the terms of Sections 1 and 2 above on a medium
2221     customarily used for software interchange; or,
2222
2223     c) Accompany it with the information you received as to the offer
2224     to distribute corresponding source code.  (This alternative is
2225     allowed only for noncommercial distribution and only if you
2226     received the program in object code or executable form with such
2227     an offer, in accord with Subsection b above.)
2228
2229 The source code for a work means the preferred form of the work for
2230 making modifications to it.  For an executable work, complete source
2231 code means all the source code for all modules it contains, plus any
2232 associated interface definition files, plus the scripts used to
2233 control compilation and installation of the executable.  However, as a
2234 special exception, the source code distributed need not include
2235 anything that is normally distributed (in either source or binary
2236 form) with the major components (compiler, kernel, and so on) of the
2237 operating system on which the executable runs, unless that component
2238 itself accompanies the executable.
2239
2240 If distribution of executable or object code is made by offering
2241 access to copy from a designated place, then offering equivalent
2242 access to copy the source code from the same place counts as
2243 distribution of the source code, even though third parties are not
2244 compelled to copy the source along with the object code.
2245
2246   4. You may not copy, modify, sublicense, or distribute the Program
2247 except as expressly provided under this License.  Any attempt
2248 otherwise to copy, modify, sublicense or distribute the Program is
2249 void, and will automatically terminate your rights under this License.
2250 However, parties who have received copies, or rights, from you under
2251 this License will not have their licenses terminated so long as such
2252 parties remain in full compliance.
2253
2254   5. You are not required to accept this License, since you have not
2255 signed it.  However, nothing else grants you permission to modify or
2256 distribute the Program or its derivative works.  These actions are
2257 prohibited by law if you do not accept this License.  Therefore, by
2258 modifying or distributing the Program (or any work based on the
2259 Program), you indicate your acceptance of this License to do so, and
2260 all its terms and conditions for copying, distributing or modifying
2261 the Program or works based on it.
2262
2263   6. Each time you redistribute the Program (or any work based on the
2264 Program), the recipient automatically receives a license from the
2265 original licensor to copy, distribute or modify the Program subject to
2266 these terms and conditions.  You may not impose any further
2267 restrictions on the recipients' exercise of the rights granted herein.
2268 You are not responsible for enforcing compliance by third parties to
2269 this License.
2270
2271   7. If, as a consequence of a court judgment or allegation of patent
2272 infringement or for any other reason (not limited to patent issues),
2273 conditions are imposed on you (whether by court order, agreement or
2274 otherwise) that contradict the conditions of this License, they do not
2275 excuse you from the conditions of this License.  If you cannot
2276 distribute so as to satisfy simultaneously your obligations under this
2277 License and any other pertinent obligations, then as a consequence you
2278 may not distribute the Program at all.  For example, if a patent
2279 license would not permit royalty-free redistribution of the Program by
2280 all those who receive copies directly or indirectly through you, then
2281 the only way you could satisfy both it and this License would be to
2282 refrain entirely from distribution of the Program.
2283
2284 If any portion of this section is held invalid or unenforceable under
2285 any particular circumstance, the balance of the section is intended to
2286 apply and the section as a whole is intended to apply in other
2287 circumstances.
2288
2289 It is not the purpose of this section to induce you to infringe any
2290 patents or other property right claims or to contest validity of any
2291 such claims; this section has the sole purpose of protecting the
2292 integrity of the free software distribution system, which is
2293 implemented by public license practices.  Many people have made
2294 generous contributions to the wide range of software distributed
2295 through that system in reliance on consistent application of that
2296 system; it is up to the author/donor to decide if he or she is willing
2297 to distribute software through any other system and a licensee cannot
2298 impose that choice.
2299
2300 This section is intended to make thoroughly clear what is believed to
2301 be a consequence of the rest of this License.
2302
2303   8. If the distribution and/or use of the Program is restricted in
2304 certain countries either by patents or by copyrighted interfaces, the
2305 original copyright holder who places the Program under this License
2306 may add an explicit geographical distribution limitation excluding
2307 those countries, so that distribution is permitted only in or among
2308 countries not thus excluded.  In such case, this License incorporates
2309 the limitation as if written in the body of this License.
2310
2311   9. The Free Software Foundation may publish revised and/or new versions
2312 of the General Public License from time to time.  Such new versions will
2313 be similar in spirit to the present version, but may differ in detail to
2314 address new problems or concerns.
2315
2316 Each version is given a distinguishing version number.  If the Program
2317 specifies a version number of this License which applies to it and "any
2318 later version", you have the option of following the terms and conditions
2319 either of that version or of any later version published by the Free
2320 Software Foundation.  If the Program does not specify a version number of
2321 this License, you may choose any version ever published by the Free Software
2322 Foundation.
2323
2324   10. If you wish to incorporate parts of the Program into other free
2325 programs whose distribution conditions are different, write to the author
2326 to ask for permission.  For software which is copyrighted by the Free
2327 Software Foundation, write to the Free Software Foundation; we sometimes
2328 make exceptions for this.  Our decision will be guided by the two goals
2329 of preserving the free status of all derivatives of our free software and
2330 of promoting the sharing and reuse of software generally.
2331
2332                             NO WARRANTY
2333
2334   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2335 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
2336 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2337 PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2338 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2339 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
2340 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
2341 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2342 REPAIR OR CORRECTION.
2343
2344   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2345 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2346 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2347 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2348 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2349 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2350 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2351 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2352 POSSIBILITY OF SUCH DAMAGES.
2353
2354                      END OF TERMS AND CONDITIONS
2355
2356    </screen>
2357   </sect1>
2358  </appendix>
2359 </book>
2360
2361  <!-- Keep this comment at the end of the file
2362  Local variables:
2363  mode: sgml
2364  sgml-omittag:t
2365  sgml-shorttag:t
2366  sgml-minimize-attributes:nil
2367  sgml-always-quote-attributes:t
2368  sgml-indent-step:1
2369  sgml-indent-data:t
2370  sgml-parent-document: nil
2371  sgml-local-catalogs: nil
2372  sgml-namecase-general:t
2373  End:
2374  -->