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