Debian installation procedure

[metaproxy-moved-to-github.git] / doc / book.xml

<!-- $Id: book.xml,v 1.27 2006-04-27 19:49:35 adam Exp $ -->
 <bookinfo>
  <title>Metaproxy - User's Guide and Reference</title>
  <author>
   <firstname>Mike</firstname><surname>Taylor</surname>
  </author>
  <author>
   <firstname>Adam</firstname><surname>Dickmeiss</surname>
  </author>
  <copyright>
   <year>2006</year>
   <holder>Index Data ApS</holder>
  </copyright>
  <abstract>
   <simpara>
    Metaproxy is a universal router, proxy and encapsulated
    metasearcher for information retrieval protocols.  It accepts,
    processes, interprets and redirects requests from IR clients using
    standard protocols such as
    <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink>
    (and in the future <ulink url="&url.sru;">SRU</ulink>
    and <ulink url="&url.srw;">SRW</ulink>), as
    well as functioning as a limited
    <ulink url="&url.http;">HTTP</ulink> server. 
    Metaproxy is configured by an XML file which
    specifies how the software should function in terms of routes that
    the request packets can take through the proxy, each step on a
    route being an instantiation of a filter.  Filters come in many
    types, one for each operation: accepting Z39.50 packets, logging,
    query transformation, multiplexing, etc.  Further filter-types can
    be added as loadable modules to extend Metaproxy functionality,
    using the filter API.
   </simpara>
   <simpara>
    The terms under which Metaproxy will be distributed have yet to be
    established, but it will not necessarily be open source; so users
    should not at this stage redistribute the code without explicit
    written permission from the copyright holders, Index Data ApS.
   </simpara>
   <simpara>
    <inlinemediaobject>
     <imageobject>
      <imagedata fileref="common/id.png" format="PNG"/>
     </imageobject>
     <imageobject>
      <imagedata fileref="common/id.eps" format="EPS"/>
     </imageobject>
    </inlinemediaobject>
   </simpara>
  </abstract>
 </bookinfo>

 <chapter id="introduction">
  <title>Introduction</title>
  
  
  <para>
   <ulink url="&url.metaproxy;">Metaproxy</ulink>
   is a standalone program that acts as a universal router, proxy and
   encapsulated metasearcher for information retrieval protocols such
   as <ulink url="&url.z39.50;">Z39.50</ulink>, and in the future
   <ulink url="&url.sru;">SRU</ulink> and <ulink url="&url.srw;">SRW</ulink>.
   To clients, it acts as a server of these protocols: it can be searched,
   records can be retrieved from it, etc. 
   To servers, it acts as a client: it searches in them,
   retrieves records from them, etc.  it satisfies its clients'
   requests by transforming them, multiplexing them, forwarding them
   on to zero or more servers, merging the results, transforming
   them, and delivering them back to the client.  In addition, it
   acts as a simple <ulink url="&url.http;">HTTP</ulink> server; support
   for further protocols can be added in a modular fashion, through the
   creation of new filters.
  </para>
  <screen>
   Anything goes in!
   Anything goes out!
   Fish, bananas, cold pyjamas,
   Mutton, beef and trout!
        - attributed to Cole Porter.
  </screen>
  <para>
   Metaproxy is a more capable alternative to
   <ulink url="&url.yazproxy;">YAZ Proxy</ulink>,
   being more powerful, flexible, configurable and extensible.  Among
   its many advantages over the older, more pedestrian work are
   support for multiplexing (encapsulated metasearching), routing by
   database name, authentication and authorisation and serving local
   files via HTTP.  Equally significant, its modular architecture
   facilitites the creation of pluggable modules implementing further
   functionality.
  </para>
  <para>
   This manual will briefly describe Metaproxy's licensing situation
   before giving an overview of its architecture, then discussing the
   key concept of a filter in some depth and giving an overview of
   the various filter types, then discussing the configuration file
   format.  After this come several optional chapters which may be
   freely skipped: a detailed discussion of virtual databases and
   multi-database searching, some notes on writing extensions
   (additional filter types) and a high-level description of the
   source code.  Finally comes the reference guide, which contains
   instructions for invoking the <command>metaproxy</command>
   program, and detailed information on each type of filter,
   including examples.
  </para>
 </chapter>



 <chapter id="licence">
  <title>The Metaproxy Licence</title>
  <para>
   <emphasis role="strong">
    No decision has yet been made on the terms under which
    Metaproxy will be distributed.
   </emphasis>
   It is possible that, unlike
   other Index Data products, metaproxy may not be released under a
   free-software licence such as the GNU GPL.  Until a decision is
   made and a public statement made, then, and unless it has been
   delivered to you other specific terms, please treat Metaproxy as
   though it were proprietary software.
   The code should not be redistributed without explicit
   written permission from the copyright holders, Index Data ApS.
  </para>
 </chapter>

 <chapter id="installation">
  <title>Installation</title>
  <para>
   Metaproxy depends on the following tools/libraries:
   <variablelist>
    <varlistentry><term><ulink url="&url.yazplusplus;">YAZ++</ulink></term>
     <listitem>
      <para>
       This is a C++ library based on <ulink url="&url.yaz;">YAZ</ulink>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term><ulink url="&url.libxslt;">Libxslt</ulink></term>
     <listitem>
      <para>This is an XSLT processor - based on 
       <ulink url="&url.libxml2;">Libxml2</ulink>. Both Libxml2 and
       Libxslt must be installed with the development components
       (header files, etc.) as well as the run-time libraries.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term><ulink url="&url.boost;">Boost</ulink></term>
     <listitem>
      <para>
       The popular C++ library. Initial versions of Metaproxy
       was built with 1.33.0. Version 1.33.1 works too.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <para>
   In order to compile Metaproxy a modern C++ compiler is
   required. Boost, in particular, requires the C++ compiler
   to facilitate the newest features. Refer to Boost
   <ulink url="&url.boost.compilers.status;">Compiler Status</ulink>
   for more information.
  </para>
  <para>
   We have succesfully built Metaproxy using the compilers
   <ulink url="&url.gcc;">GCC</ulink> version 4.0 and
   <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink> 2003/2005.
  </para>

  <section id="installation.unix">
   <title>Installation on Unix (from Source)</title>
   <para>
    Here is a quick step-by-step guide on how to compile all the
    tools that Metaproxy uses. Only few systems have none of the required
    tools binary packages. If, for example, Libxml2/libxslt are already
    installed as development packages use those (and omit compilation).
   </para>
   
   <para>
    Libxml2/libxslt:
   </para>
   <screen>
    gunzip -c libxml2-version.tar.gz|tar xf -
    cd libxml2-version
    ./configure
    make
    su
    make install
   </screen>
   <screen>
    gunzip -c libxslt-version.tar.gz|tar xf -
    cd libxslt-version
    ./configure
    make
    su
    make install
   </screen>
   <para>
    YAZ/YAZ++:
   </para>
   <screen>
    gunzip -c yaz-version.tar.gz|tar xf -
    cd yaz-version
    ./configure
    make
    su
    make install
   </screen>
   <screen>
    gunzip -c yazpp-version.tar.gz|tar xf -
    cd yazpp-version
    ./configure
    make
    su
    make install
   </screen>
   <para>
    Boost:
   </para>
   <screen>
    gunzip -c boost-version.tar.gz|tar xf -
    cd boost-version
    ./configure
    make
    su
    make install
   </screen>
   <para>
    Metaproxy:
   </para>
   <screen>
    gunzip -c metaproxy-version.tar.gz|tar xf -
    cd metaproxy-version
    ./configure
    make
    su
    make install
   </screen>
  </section>

  <section id="installation.debian">
   <title>Installation on Debian GNU/Linux</title>
   <para>
    All dependencies for Metaproxy are available as 
    <ulink url="&url.debian;">Debian</ulink>
    packages for the sarge (stable in 2005) and etch (testing in 2005)
    distributions.
   </para>
   <para>
    The procedures for Debian based systems, such as
    <ulink url="&url.ubuntu;">Ubuntu</ulink> is probably similar
   </para>
   <para>
    There is currently no official Debian package for YAZ++.
    And the Debian package for YAZ is probably too old.
    Update the <filename>/etc/apt/sources.list</filename>
    to include the Index Data repository.
    See YAZ' <ulink url="&url.yaz.download.debian;">Download Debian</ulink>
    for more information.
   </para>
   <screen>
    apt-get install libxslt1-dev
    apt-get install libyazpp-dev
    apt-get install libboost-dev
    apt-get install libboost-thread-dev
    apt-get install libboost-date-time-dev
    apt-get install libboost-program-options-dev
    apt-get install libboost-test-dev
   </screen>
   <para>
    With these packages installed, the usual configure + make
    procedure can be used for Metaproxy as outlined in
    <xref linkend="installation.unix"/>.
   </para>
  </section>

  <section id="installation.windows">
   <title>Installation on Windows</title>
   <para>
    Compilation of Metaproxy can be done using
    Microsoft <ulink url="&url.vstudio;">Visual Studio</ulink>.
    We know Version 2003 works. We expect Version 2005 to
    work as well.
   </para>
   <section id="installation.windows.boost">
    <title>Boost</title>
    <para>
     Get Boost from its <ulink url="&url.boost;">home page</ulink>.
     You also need Boost Jam (an alternative to make).
     That's also available from the Boost home page.
     The files to be downloaded are called something like:
     <filename>boost_1_33-1.exe</filename>
     and
     <filename>boost-jam-3.1.12-1-ntx86.zip</filename>.
     Unpack Boost Jam first. Put <filename>bjam.exe</filename>
     in your system path. Make a command prompt and ensure
     it can be found automatically. If not check the PATH.
     The Boost .exe is a self-extracting exe with
     complete source for Boost. Compile that source with
     Boost Jam (An alternative to Make).
     The compilation takes a while.
     By default, the Boost build process puts the resulting
     libraries + header files in
     <literal>\boost\lib</literal>, <literal>\boost\include</literal>.
    </para>
    <para>
     For more informatation about installing Boost refer to the
     <ulink url="&url.boost.getting.started;">getting started</ulink>
     pages.
    </para>
   </section>

   <section id="installation.windows.libxslt">
    <title>Libxslt</title>
    <para>
     <ulink url="&url.libxslt;">Libxslt</ulink> can be downloaded
     for Windows from
     <ulink url="&url.libxml2.download.win32;">here</ulink>.
    </para>
    <para>
     Libxslt has other dependencies, but thes can all be downloaded
     from the same site. Get the following:
     iconv, zlib, libxml2, libxslt.
    </para>
   </section>

   <section id="installation.windows.yaz">
    <title>YAZ</title>
    <para>
     <ulink url="&url.yaz;">YAZ</ulink> can be downloaded
     for Windows from
     <ulink url="&url.yaz.download.win32;">here</ulink>.
    </para>
   </section>

   <section id="installation.windows.yazplusplus">
    <title>YAZ++</title>
    <para>
     Get <ulink url="&url.yazplusplus;">YAZ++</ulink> as well.
     Version 1.0 or later is required. For now get it from
     Index Data's
     <ulink url="&url.snapshot.download;">Snapshot area</ulink>.
    </para>
    <para>
     YAZ++ includes NMAKE makefiles, similar to those found in the
     YAZ package.
    </para>
   </section>

   <section id="installation.windows.metaproxy">
    <title>Metaproxy</title>
    <para>
     Metaproxy is shipped with NMAKE makfiles as well - similar
     to those found in the YAZ++/YAZ packages. Adjust this Makefile
     to point to the proper locations of Boost, Libxslt, Libxml2,
     zlib, iconv, yaz and yazpp.
    </para>
    <para>
     After succesful compilation you'll find
     <literal>metaproxy.exe</literal> in the
     <literal>bin</literal> directory.
    </para>
   </section>

  </section>
 </chapter>
 
 <chapter id="architecture">
  <title>The Metaproxy Architecture</title>
  <para>
   The Metaproxy architecture is based on three concepts:
   the <emphasis>package</emphasis>,
   the <emphasis>route</emphasis>
   and the <emphasis>filter</emphasis>.
  </para>
  <variablelist>
   <varlistentry>
    <term>Packages</term>
    <listitem>
     <para>
      A package is request or response, encoded in some protocol,
      issued by a client, making its way through Metaproxy, send to or
      received from a server, or sent back to the client.
     </para>
     <para>
      The core of a package is the protocol unit - for example, a
      Z39.50 Init Request or Search Response, or an SRU searchRetrieve
      URL or Explain Response.  In addition to this core, a package
      also carries some extra information added and used by Metaproxy
      itself.
     </para>
     <para>
      In general, packages are doctored as they pass through
      Metaproxy.  For example, when the proxy performs authentication
      and authorisation on a Z39.50 Init request, it removes the
      authentication credentials from the package so that they are not
      passed onto the back-end server; and when search-response
      packages are obtained from multiple servers, they are merged
      into a single unified package that makes its way back to the
      client.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Routes</term>
    <listitem>
     <para>
      Packages make their way through routes, which can be thought of
      as programs that operate on the package data-type.  Each
      incoming package initially makes its way through a default
      route, but may be switched to a different route based on various
      considerations.  Routes are made up of sequences of filters (see
      below).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Filters</term>
    <listitem>
     <para>
      Filters provide the individual instructions within a route, and
      effect the necessary transformations on packages.  A particular
      configuration of Metaproxy is essentially a set of filters,
      described by configuration details and arranged in order in one
      or more routes.  There are many kinds of filter - about a dozen
      at the time of writing with more appearing all the time - each
      performing a specific function and configured by different
      information.
     </para>
     <para>
      The word ``filter'' is sometimes used rather loosely, in two
      different ways: it may be used to mean a particular
      <emphasis>type</emphasis> of filter, as when we speak of ``the
      auth_simplefilter'' or ``the multi filter''; or it may be used
      to be a specific <emphasis>instance</emphasis> of a filter
      within a Metaproxy configuration.  For example, a single
      configuration will often contain multiple instances of the
      <literal>z3950_client</literal> filter.  In
      operational terms, of these is a separate filter.  In practice,
      context always make it clear which sense of the word ``filter''
      is being used.
     </para>
     <para>
      Extensibility of Metaproxy is primarily through the creation of
      plugins that provide new filters.  The filter API is small and
      conceptually simple, but there are many details to master.  See
      the section below on
      <link linkend="extensions">extensions</link>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
  <para>
   Since packages are created and handled by the system itself, and
   routes are conceptually simple, most of the remainder of this
   document concentrates on filters.  After a brief overview of the
   filter types follows, along with some thoughts on possible future
   directions.
  </para>
 </chapter>



 <chapter id="filters">
  <title>Filters</title>
  
  
  <section>
   <title>Introductory notes</title>
   <para>
    It's useful to think of Metaproxy as an interpreter providing a small
    number of primitives and operations, but operating on a very
    complex data type, namely the ``package''.
   </para>
   <para>
    A package represents a Z39.50 or SRU/W request (whether for Init,
    Search, Scan, etc.)  together with information about where it came
    from.  Packages are created by front-end filters such as
    <literal>frontend_net</literal> (see below), which reads them from
    the network; other front-end filters are possible.  They then pass
    along a route consisting of a sequence of filters, each of which
    transforms the package and may also have side-effects such as
    generating logging.  Eventually, the route will yield a response,
    which is sent back to the origin.
   </para>
   <para>
    There are many kinds of filter: some that are defined statically
    as part of Metaproxy, and others may be provided by third parties
    and dynamically loaded.  They all conform to the same simple API
    of essentially two methods: <function>configure()</function> is
    called at startup time, and is passed a DOM tree representing that
    part of the configuration file that pertains to this filter
    instance: it is expected to walk that tree extracting relevant
    information; and <function>process()</function> is called every
    time the filter has to processes a package.
   </para>
   <para>
    While all filters provide the same API, there are different modes
    of functionality.  Some filters are sources: they create
    packages
    (<literal>frontend_net</literal>);
    others are sinks: they consume packages and return a result
    (<literal>z3950_client</literal>,
    <literal>backend_test</literal>,
    <literal>http_file</literal>);
    the others are true filters, that read, process and pass on the
    packages they are fed
    (<literal>auth_simple</literal>,
    <literal>log</literal>,
    <literal>multi</literal>,
    <literal>query_rewrite</literal>,
    <literal>session_shared</literal>,
    <literal>template</literal>,
    <literal>virt_db</literal>).
   </para>
 </section>
  
  
  <section id="overview.filter.types">
   <title>Overview of filter types</title>
   <para>
    We now briefly consider each of the types of filter supported by
    the core Metaproxy binary.  This overview is intended to give a
    flavour of the available functionality; more detailed information
    about each type of filter is included below in
    <link linkend="filterref"
          >the reference guide to Metaproxy filters</link>.
   </para>
   <para>
    The filters are here named by the string that is used as the
    <literal>type</literal> attribute of a
    <literal>&lt;filter&gt;</literal> element in the configuration
    file to request them, with the name of the class that implements
    them in parentheses.  (The classname is not needed for normal
    configuration and use of Metaproxy; it is useful only to
    developers.)
   </para>
   <para>
    The filters are here listed in alphabetical order:
   </para>
   
   <section>
    <title><literal>auth_simple</literal>
     (mp::filter::AuthSimple)</title>
    <para>
     Simple authentication and authorisation.  The configuration
     specifies the name of a file that is the user register, which
     lists <varname>username</varname>:<varname>password</varname>
     pairs, one per line, colon separated. When a session begins, it
     is rejected unless username and passsword are supplied, and match
     a pair in the register.  The configuration file may also specific
     the name of another file that is the target register: this lists
     lists <varname>username</varname>:<varname>dbname</varname>,<varname>dbname</varname>...
     sets, one per line, with multiple database names separated by
     commas.  When a search is processed, it is rejected unless the
     database to be searched is one of those listed as available to
     the user.
    </para>
   </section>
   
   <section>
    <title><literal>backend_test</literal>
    (mp::filter::Backend_test)</title>
    <para>
     A sink that provides dummy responses in the manner of the
     <literal>yaz-ztest</literal> Z39.50 server.  This is useful only
     for testing.  Seriously, you don't need this.  Pretend you didn't
     even read this section.
    </para>
   </section>
   
   <section>
    <title><literal>frontend_net</literal>
     (mp::filter::FrontendNet)</title>
    <para>
     A source that accepts Z39.50 connections from a port
     specified in the configuration, reads protocol units, and
     feeds them into the next filter in the route.  When the result is
     revceived, it is returned to the original origin.
    </para>
   </section>

   <section>
    <title><literal>http_file</literal>
     (mp::filter::HttpFile)</title>
    <para>
     A sink that returns the contents of files from the local
     filesystem in response to HTTP requests.  (Yes, Virginia, this
     does mean that Metaproxy is also a Web-server in its spare time.  So
     far it does not contain either an email-reader or a Lisp
     interpreter, but that day is surely coming.)
    </para>
   </section>
   
   <section>
    <title><literal>log</literal>
     (mp::filter::Log)</title>
    <para>
     Writes logging information to standard output, and passes on
     the package unchanged.
   </para>
   </section>
   
   <section>
   <title><literal>multi</literal>
     (mp::filter::Multi)</title>
    <para>
     Performs multi-database searching.
     See
     <link linkend="multidb">the extended discussion</link>
     of virtual databases and multi-database searching below.
    </para>
   </section>
   
   <section>
   <title><literal>query_rewrite</literal>
     (mp::filter::QueryRewrite)</title>
    <para>
     Rewrites Z39.50 Type-1 and Type-101 (``RPN'') queries by a
     three-step process: the query is transliterated from Z39.50
     packet structures into an XML representation; that XML
     representation is transformed by an XSLT stylesheet; and the
     resulting XML is transliterated back into the Z39.50 packet
     structure.
    </para>
   </section>
   
   <section>
    <title><literal>session_shared</literal>
     (mp::filter::SessionShared)</title>
    <para>
     When this is finished, it will implement global sharing of
     result sets (i.e. between threads and therefore between
     clients), yielding performance improvements especially when
     incoming requests are from a stateless environment such as a
     web-server, in which the client process representing a session
     might be any one of many.  However:
    </para>
    <warning>
     <para>
      This filter is not yet completed.
     </para>
    </warning>
   </section>
   
   <section>
    <title><literal>template</literal>
     (mp::filter::Template)</title>
    <para>
     Does nothing at all, merely passing the packet on.  (Maybe it
     should be called <literal>nop</literal> or
     <literal>passthrough</literal>?)  This exists not to be used, but
     to be copied - to become the skeleton of new filters as they are
     written.  As with <literal>backend_test</literal>, this is not
     intended for civilians.
    </para>
   </section>
   
   <section>
    <title><literal>virt_db</literal>
     (mp::filter::Virt_db)</title>
    <para>
     Performs virtual database selection: based on the name of the
     database in the search request, a server is selected, and its
     address added to the request in a <literal>VAL_PROXY</literal>
     otherInfo packet.  It will subsequently be used by a
     <literal>z3950_client</literal> filter.
     See
     <link linkend="multidb">the extended discussion</link>
     of virtual databases and multi-database searching below.
    </para>
   </section>
   
   <section>
    <title><literal>z3950_client</literal>
     (mp::filter::Z3950Client)</title>
    <para>
     Performs Z39.50 searching and retrieval by proxying the
     packages that are passed to it.  Init requests are sent to the
     address specified in the <literal>VAL_PROXY</literal> otherInfo
     attached to the request: this may have been specified by client,
     or generated by a <literal>virt_db</literal> filter earlier in
     the route.  Subsequent requests are sent to the same address,
     which is remembered at Init time in a Session object.
    </para>
  </section>
  </section>
  
  
  <section id="future.directions">
   <title>Future directions</title>
  <para>
    Some other filters that do not yet exist, but which would be
    useful, are briefly described.  These may be added in future
    releases (or may be created by third parties, as loadable
    modules).
   </para>

   <variablelist>
    <varlistentry>
     <term><literal>frontend_cli</literal> (source)</term>
    <listitem>
      <para>
       Command-line interface for generating requests.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>frontend_sru</literal> (source)</term>
     <listitem>
      <para>
       Receive SRU (and perhaps SRW) requests.
     </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>sru2z3950</literal> (filter)</term>
     <listitem>
      <para>
       Translate SRU requests into Z39.50 requests.
     </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>sru_client</literal> (sink)</term>
     <listitem>
      <para>
       SRU searching and retrieval.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>srw_client</literal> (sink)</term>
     <listitem>
      <para>
       SRW searching and retrieval.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>opensearch_client</literal> (sink)</term>
     <listitem>
      <para>
       A9 OpenSearch searching and retrieval.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
 </chapter>
 
 
 
 <chapter id="configuration">
  <title>Configuration: the Metaproxy configuration file format</title>
  
  
  <section>
   <title>Introductory notes</title>
   <para>
    If Metaproxy is an interpreter providing operations on packages, then
    its configuration file can be thought of as a program for that
    interpreter.  Configuration is by means of a single file, the name
    of which is supplied as the sole command-line argument to the
    <command>metaproxy</command> program.  (See
    <link linkend="progref">the reference guide</link>
    below for more information on invoking Metaproxy.)
   </para>
   <para>
    The configuration files are written in XML.  (But that's just an
    implementation detail - they could just as well have been written
    in YAML or Lisp-like S-expressions, or in a custom syntax.)
   </para>
   <para>
    Since XML has been chosen, an XML schema,
    <filename>config.xsd</filename>, is provided for validating
    configuration files.  This file is supplied in the
    <filename>etc</filename> directory of the Metaproxy distribution.  It
    can be used by (among other tools) the <command>xmllint</command>
    program supplied as part of the <literal>libxml2</literal>
    distribution:
   </para>
   <screen>
    xmllint --noout --schema etc/config.xsd my-config-file.xml
   </screen>
   <para>
    (A recent version of <literal>libxml2</literal> is required, as
    support for XML Schemas is a relatively recent addition.)
   </para>
  </section>
  
  <section id="overview.xml.structure">
   <title>Overview of XML structure</title>
   <para>
    All elements and attributes are in the namespace
    <ulink url="http://indexdata.dk/yp2/config/1"/>.
     This is most easily achieved by setting the default namespace on
     the top-level element, as here:
   </para>
   <screen>
    &lt;yp2 xmlns="http://indexdata.dk/yp2/config/1"&gt;
   </screen>
   <para>
    The top-level element is &lt;yp2&gt;.  This contains a
    &lt;start&gt; element, a &lt;filters&gt; element and a
    &lt;routes&gt; element, in that order.  &lt;filters&gt; is
    optional; the other two are mandatory.  All three are
    non-repeatable.
   </para>
  <para>
    The &lt;start&gt; element is empty, but carries a
    <literal>route</literal> attribute, whose value is the name of
    route at which to start running - analogous to the name of the
    start production in a formal grammar.
   </para>
  <para>
    If present, &lt;filters&gt; contains zero or more &lt;filter&gt;
    elements.  Each filter carries a <literal>type</literal> attribute
    which specifies what kind of filter is being defined
    (<literal>frontend_net</literal>, <literal>log</literal>, etc.)
    and contain various elements that provide suitable configuration
    for a filter of its type.  The filter-specific elements are
    described in
    <link linkend="filterref">the reference guide below</link>.
    Filters defined in this part of the file must carry an
    <literal>id</literal> attribute so that they can be referenced
    from elsewhere.
   </para>
   <para>
    &lt;routes&gt; contains one or more &lt;route&gt; elements, each
    of which must carry an <literal>id</literal> element.  One of the
    routes must have the ID value that was specified as the start
    route in the &lt;start&gt; element's <literal>route</literal>
    attribute.  Each route contains zero or more &lt;filter&gt;
    elements.  These are of two types.  They may be empty, but carry a
    <literal>refid</literal> attribute whose value is the same as the
    <literal>id</literal> of a filter previously defined in the
    &lt;filters&gt; section.  Alternatively, a route within a filter
    may omit the <literal>refid</literal> attribute, but contain
    configuration elements similar to those used for filters defined
    in the &lt;filters&gt; section.  (In other words, each filter in a
    route may be included either by reference or by physical
    inclusion.)
   </para>
  </section>


  <section id="example.configuration">
   <title>An example configuration</title>
   <para>
    The following is a small, but complete, Metaproxy configuration
    file (included in the distribution as
    <literal>metaproxy/etc/config0.xml</literal>).
    This file defines a very simple configuration that simply proxies
    to whatever back-end server the client requests, but logs each
    request and response.  This can be useful for debugging complex
    client-server dialogues.
   </para>
   <screen><![CDATA[<?xml version="1.0"?>
<yp2 xmlns="http://indexdata.dk/yp2/config/1">
  <start route="start"/>
  <filters>
    <filter id="frontend" type="frontend_net">
      <port>@:9000</port>
    </filter>
    <filter id="backend" type="z3950_client">
    </filter>
  </filters>
  <routes>  
    <route id="start">
      <filter refid="frontend"/>
      <filter type="log"/>
      <filter refid="backend"/>
    </route>
  </routes>
</yp2>
]]></screen>
   <para>
    It works by defining a single route, called
    <literal>start</literal>, which consists of a sequence of three
    filters.  The first and last of these are included by reference:
    their <literal>&lt;filter&gt;</literal> elements have
    <literal>refid</literal> attributes that refer to filters defined
    within the prior <literal>&lt;filters&gt;</literal> section.  The
    middle filter is included inline in the route.
   </para>
   <para>
    The three filters in the route are as follows: first, a
    <literal>frontend_net</literal> filter accepts Z39.50 requests
    from any host on port 9000; then these requests are passed through
    a <literal>log</literal> filter that emits a message for each
    request; they are then fed into a <literal>z3950_client</literal>
    filter, which forwards the requests to the client-specified
    back-end Z39.509 server.  When the response arrives, it is handed
    back to the <literal>log</literal> filter, which emits another
    message; and then to the front-end filter, which returns the
    response to the client.
   </para>
  </section>
 </chapter>



 <chapter id="multidb">
  <title>Virtual databases and multi-database searching</title>


  <section>
   <title>Introductory notes</title>
   <para>
    Two of Metaproxy's filters are concerned with multiple-database
    operations.  Of these, <literal>virt_db</literal> can work alone
    to control the routing of searches to one of a number of servers,
    while <literal>multi</literal> can work together with
    <literal>virt_db</literal> to perform multi-database searching, merging
    the results into a unified result-set - ``metasearch in a box''.
   </para>
   <para>
    The interaction between
    these two filters is necessarily complex: it reflects the real,
    irreducible complexity of multi-database searching in a protocol such
    as Z39.50 that separates initialisation from searching, and in
    which the database to be searched is not known at initialisation
    time.
   </para>
   <para>
    It's possible to use these filters without understanding the
    details of their functioning and the interaction between them; the
    next two sections of this chapter are ``HOWTO'' guides for doing
    just that.  However, debugging complex configurations will require
    a deeper understanding, which the last two sections of this
    chapters attempt to provide.
   </para>
  </section>


  <section id="multidb.virt_db">
   <title>Virtual databases with the <literal>virt_db</literal> filter</title>
   <para>
    Working alone, the purpose of the
    <literal>virt_db</literal>
    filter is to route search requests to one of a selection of
    back-end databases.  In this way, a single Z39.50 endpoint
    (running Metaproxy) can provide access to several different
    underlying services, including those that would otherwise be
    inaccessible due to firewalls.  In many useful configurations, the
    back-end databases are local to the Metaproxy installation, but
    the software does not enforce this, and any valid Z39.50 servers
    may be used as back-ends.
   </para>
   <para>
    For example, a <literal>virt_db</literal>
    filter could be set up so that searches in the virtual database
    ``lc'' are forwarded to the Library of Congress bibliographic
    catalogue server, and searches in the virtual database ``marc''
    are forwarded to the toy database of MARC records that Index Data
    hosts for testing purposes.  A <literal>virt_db</literal>
    configuration to make this switch would look like this:
   </para>
   <screen><![CDATA[<filter type="virt_db">
  <virtual>
    <database>lc</database>
    <target>z3950.loc.gov:7090/voyager</target>
  </virtual>
  <virtual>
    <database>marc</database>
    <target>indexdata.dk/marc</target>
  </virtual>
</filter>]]></screen>
   <para>
    As well as being useful in it own right, this filter also provides
    the foundation for multi-database searching.
   </para>
  </section>


  <section id="multidb.multi">
   <title>Multi-database search with the <literal>multi</literal> filter</title>
   <para>
    To arrange for Metaproxy to broadcast searches to multiple back-end
    servers, the configuration needs to include two components: a
    <literal>virt_db</literal>
    filter that specifies multiple
    <literal>&lt;target&gt;</literal>
    elements, and a subsequent
    <literal>multi</literal>
    filter.  Here, for example, is a complete configuration that
    broadcasts searches to both the Library of Congress catalogue and
    Index Data's tiny testing database of MARC records:
   </para>
   <screen><![CDATA[<?xml version="1.0"?>
<yp2 xmlns="http://indexdata.dk/yp2/config/1">
  <start route="start"/>
  <routes>
    <route id="start">
      <filter type="frontend_net">
        <threads>10</threads>
        <port>@:9000</port>
      </filter>
      <filter type="virt_db">
        <virtual>
          <database>lc</database>
          <target>z3950.loc.gov:7090/voyager</target>
        </virtual>
        <virtual>
          <database>marc</database>
          <target>indexdata.dk/marc</target>
        </virtual>
        <virtual>
          <database>all</database>
          <target>z3950.loc.gov:7090/voyager</target>
          <target>indexdata.dk/marc</target>
        </virtual>
      </filter>
      <filter type="multi"/>
      <filter type="z3950_client">
        <timeout>30</timeout>
      </filter>
    </route>
  </routes>
</yp2>]]></screen>
   <para>
    (Using a
    <literal>virt_db</literal>
    filter that specifies multiple
    <literal>&lt;target&gt;</literal>
    elements but without a subsequent
    <literal>multi</literal>
    filter yields surprising and undesirable results, as will be
    described below.  Don't do that.)
   </para>
   <para>
    Metaproxy can be invoked with this configuration as follows:
   </para>
   <screen>../src/metaproxy --config config-simple-multi.xml</screen>
   <para>
    And thereafter, Z39.50 clients can connect to the running server
    (on port 9000, as specified in the configuration) and search in
    any of the databases
    <literal>lc</literal> (the Library of Congress catalogue),
    <literal>marc</literal> (Index Data's test database of MARC records)
    or
    <literal>all</literal> (both of these).  As an example, a session
    using the YAZ command-line client <literal>yaz-client</literal> is
    here included (edited for brevity and clarity):
   </para>
   <screen><![CDATA[$ yaz-client @:9000
Connecting...OK.
Z> base lc
Z> find computer
Search was a success.
Number of hits: 10000, setno 1
Elapsed: 5.521070
Z> base marc
Z> find computer
Search was a success.
Number of hits: 10, setno 3
Elapsed: 0.060187
Z> base all
Z> find computer
Search was a success.
Number of hits: 10010, setno 4
Elapsed: 2.237648
Z> show 1
[marc]Record type: USmarc
001    11224466
003 DLC
005 00000000000000.0
008 910710c19910701nju           00010 eng
010    $a 11224466
040    $a DLC $c DLC
050 00 $a 123-xyz
100 10 $a Jack Collins
245 10 $a How to program a computer
260 1  $a Penguin
263    $a 8710
300    $a p. cm.
Elapsed: 0.119612
Z> show 2
[VOYAGER]Record type: USmarc
001 13339105
005 20041229102447.0
008 030910s2004    caua          000 0 eng
035    $a (DLC)  2003112666
906    $a 7 $b cbc $c orignew $d 4 $e epcn $f 20 $g y-gencatlg
925 0  $a acquire $b 1 shelf copy $x policy default
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.
010    $a   2003112666
020    $a 0761542892
040    $a DLC $c DLC $d DLC
050 00 $a MLCM 2004/03312 (G)
245 10 $a 007, everything or nothing : $b Prima's official strategy guide / $c created by Kaizen Media Group.
246 3  $a Double-O-seven, everything or nothing
246 30 $a Prima's official strategy guide
260    $a Roseville, CA : $b Prima Games, $c c2004.
300    $a 161 p. : $b col. ill. ; $c 28 cm.
500    $a "Platforms: Nintendo GameCube, Macintosh, PC, PlayStation 2 computer entertainment system, Xbox"--P. [4] of cover.
650  0 $a Video games.
710 2  $a Kaizen Media Group.
856 42 $3 Publisher description $u http://www.loc.gov/catdir/description/random052/2003112666.html
Elapsed: 0.150623
Z>
]]></screen>
   <para>
    As can be seen, the first record in the result set is from the
    Index Data test database, and the second from the Library of
    Congress database.  The result-set continues alternating records
    round-robin style until the point where one of the databases'
    records are exhausted.
   </para>
   <para>
    This example uses only two back-end databases; more may be used.
    There is no limitation imposed on the number of databases that may
    be metasearched in this way: issues of resource usage and
    administrative complexity dictate the practical limits.
   </para>
  </section>


  <section id="multidb.what">
   <title>What's going on?</title>
   <warning>
    <title>Lark's vomit</title>
    <para>
     This section goes into a level of technical detail that is
     probably not necessary in order to configure and use Metaproxy.
     It is provided only for those who like to know how things work.
     You should feel free to skip on to the next section if this one
     doesn't seem like fun.
    </para>
   </warning>
   <para>
    Hold on tight - this may get a little hairy.
   </para>
   <para>
    In the general course of things, a Z39.50 Init request may carry
    with it an otherInfo packet of type <literal>VAL_PROXY</literal>,
    whose value indicates the address of a Z39.50 server to which the
    ultimate connection is to be made.  (This otherInfo packet is
    supported by YAZ-based Z39.50 clients and servers, but has not yet
    been ratified by the Maintenance Agency and so is not widely used
    in non-Index Data software.  We're working on it.)
    The <literal>VAL_PROXY</literal> packet functions
    analogously to the absoluteURI-style Request-URI used with the GET
    method when a web browser asks a proxy to forward its request: see
    the
    <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2"
           >Request-URI</ulink>
    section of
    <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"
           >the HTTP 1.1 specification</ulink>.
   </para>
   <para>
    The role of the <literal>virt_db</literal> filter is to rewrite
    this otherInfo packet dependent on the virtual database that the
    client wants to search.  
   </para>
   <para>
    When Metaproxy receives a Z39.50 Init request from a client, it
    doesn't immediately forward that request to the back-end server.
    Why not?  Because it doesn't know <emphasis>which</emphasis>
    back-end server to forward it to until the client sends a search
    request that specifies the database that it wants to search in.
    Instead, it just treasures the Init request up in its heart; and,
    later, the first time the client does a search on one of the
    specified virtual databases, a connection is forged to the
    appropriate server and the Init request is forwarded to it.  If,
    later in the session, the same client searches in a different
    virtual database, then a connection is forged to the server that
    hosts it, and the same cached Init request is forwarded there,
    too.
   </para>
   <para>
    All of this clever Init-delaying is done by the
    <literal>frontend_net</literal> filter.  The
    <literal>virt_db</literal> filter knows nothing about it; in
    fact, because the Init request that is received from the client
    doesn't get forwarded until a Search request is received, the
    <literal>virt_db</literal> filter (and the
    <literal>z3950_client</literal> filter behind it) doesn't even get
    invoked at Init time.  The <emphasis>only</emphasis> thing that a
    <literal>virt_db</literal> filter ever does is rewrite the
    <literal>VAL_PROXY</literal> otherInfo in the requests that pass
    through it.
   </para>
   <para>
    ### Describe the use of multiple <literal>VAL_PROXY</literal>
    otherInfos, added by <literal>virt_db</literal> and used by
    <literal>multi</literal>.
   </para>
  </section>


  <section id="multidb.picture">
   <title>A picture is worth a thousand words (but only five hundred on 64-bit architectures)</title>
   <simpara>
    <inlinemediaobject>
     <imageobject>
      <imagedata fileref="multi.pdf" format="PDF" scale="50"/>
     </imageobject>
     <imageobject>
      <imagedata fileref="multi.png" format="PNG"/>
     </imageobject>
     <textobject>
      <!-- Fall back if none of the images can be used -->
      <phrase>
       [Here there should be a diagram showing the progress of
       packages through the filters during a simple virtual-database
       search and a multi-database search, but is seems that your
       toolchain has not been able to include the diagram in this
       document.  This is because of LaTeX suckage.  Time to move to
       OpenOffice.  Yes, really.]
      </phrase>
     </textobject>
<!-- ### This used to work with an older version of DocBook
     <caption>
      <para>Caption: progress of packages through filters.</para>
     </caption>
-->
    </inlinemediaobject>
   </simpara>
  </section>
 </chapter>



 <chapter id="extensions">
  <title>Writing extensions for Metaproxy</title>
  <para>### To be written</para>
 </chapter>




 <chapter id="classes">
  <title>Classes in the Metaproxy source code</title>


  <section>
   <title>Introductory notes</title>
   <para>
    <emphasis>Stop!  Do not read this!</emphasis>
    You won't enjoy it at all.  You should just skip ahead to
    <link linkend="refguide">the reference guide</link>,
    which tells
    <!-- The remainder of this paragraph is lifted verbatim from
    Douglas Adams' _Hitch Hiker's Guide to the Galaxy_, chapter 8 -->
    you things you really need to know, like the fact that the
    fabulously beautiful planet Bethselamin is now so worried about
    the cumulative erosion by ten billion visiting tourists a year
    that any net imbalance between the amount you eat and the amount
    you excrete whilst on the planet is surgically removed from your
    bodyweight when you leave: so every time you go to the lavatory it
    is vitally important to get a receipt.
   </para>
   <para>
    This chapter contains documentation of the Metaproxy source code, and is
    of interest only to maintainers and developers.  If you need to
    change Metaproxy's behaviour or write a new filter, then you will most
    likely find this chapter helpful.  Otherwise it's a waste of your
    good time.  Seriously: go and watch a film or something.
    <citetitle>This is Spinal Tap</citetitle> is particularly good.
   </para>
   <para>
    Still here?  OK, let's continue.
   </para>
   <para>
    In general, classes seem to be named big-endianly, so that
    <literal>FactoryFilter</literal> is not a filter that filters
    factories, but a factory that produces filters; and
    <literal>FactoryStatic</literal> is a factory for the statically
    registered filters (as opposed to those that are dynamically
    loaded).
   </para>
  </section>

  <section id="individual.classes">
   <title>Individual classes</title>
   <para>
    The classes making up the Metaproxy application are here listed by
    class-name, with the names of the source files that define them in
    parentheses.
   </para>

   <section>
    <title><literal>mp::FactoryFilter</literal>
     (<filename>factory_filter.cpp</filename>)</title>
    <para>
     A factory class that exists primarily to provide the
     <literal>create()</literal> method, which takes the name of a
     filter class as its argument and returns a new filter of that
     type.  To enable this, the factory must first be populated by
     calling <literal>add_creator()</literal> for static filters (this
     is done by the <literal>FactoryStatic</literal> class, see below)
     and <literal>add_creator_dyn()</literal> for filters loaded
     dynamically.
    </para>
   </section>

   <section>
    <title><literal>mp::FactoryStatic</literal>
     (<filename>factory_static.cpp</filename>)</title>
    <para>
     A subclass of <literal>FactoryFilter</literal> which is
     responsible for registering all the statically defined filter
     types.  It does this by knowing about all those filters'
     structures, which are listed in its constructor.  Merely
     instantiating this class registers all the static classes.  It is
     for the benefit of this class that <literal>struct
      metaproxy_1_filter_struct</literal> exists, and that all the filter
     classes provide a static object of that type.
    </para>
   </section>

   <section>
    <title><literal>mp::filter::Base</literal>
     (<filename>filter.cpp</filename>)</title>
    <para>
     The virtual base class of all filters.  The filter API is, on the
     surface at least, extremely simple: two methods.
     <literal>configure()</literal> is passed a DOM tree representing
     that part of the configuration file that pertains to this filter
     instance, and is expected to walk that tree extracting relevant
     information.  And <literal>process()</literal> processes a
     package (see below).  That surface simplicitly is a bit
     misleading, as <literal>process()</literal> needs to know a lot
     about the <literal>Package</literal> class in order to do
     anything useful.
    </para>
   </section>

   <section>
    <title><literal>mp::filter::AuthSimple</literal>,
     <literal>Backend_test</literal>, etc.
     (<filename>filter_auth_simple.cpp</filename>,
     <filename>filter_backend_test.cpp</filename>, etc.)</title>
    <para>
     Individual filters.  Each of these is implemented by a header and
     a source file, named <filename>filter_*.hpp</filename> and
     <filename>filter_*.cpp</filename> respectively.  All the header
     files should be pretty much identical, in that they declare the
     class, including a private <literal>Rep</literal> class and a
     member pointer to it, and the two public methods.  The only extra
     information in any filter header is additional private types and
     members (which should really all be in the <literal>Rep</literal>
     anyway) and private methods (which should also remain known only
     to the source file, but C++'s brain-damaged design requires this
     dirty laundry to be exhibited in public.  Thanks, Bjarne!)
    </para>
    <para>
     The source file for each filter needs to supply:
    </para>
    <itemizedlist>
     <listitem>
      <para>
       A definition of the private <literal>Rep</literal> class.
      </para>
     </listitem>
     <listitem>
      <para>
       Some boilerplate constructors and destructors.
      </para>
     </listitem>
     <listitem>
      <para>
       A <literal>configure()</literal> method that uses the
       appropriate XML fragment.
      </para>
     </listitem>
     <listitem>
      <para>
       Most important, the <literal>process()</literal> method that
       does all the actual work.
      </para>
     </listitem>
    </itemizedlist>
   </section>

   <section>
    <title><literal>mp::Package</literal>
     (<filename>package.cpp</filename>)</title>
    <para>
     Represents a package on its way through the series of filters
     that make up a route.  This is essentially a Z39.50 or SRU APDU
     together with information about where it came from, which is
     modified as it passes through the various filters.
    </para>
   </section>

   <section>
    <title><literal>mp::Pipe</literal>
     (<filename>pipe.cpp</filename>)</title>
    <para>
     This class provides a compatibility layer so that we have an IPC
     mechanism that works the same under Unix and Windows.  It's not
     particularly exciting.
    </para>
   </section>

   <section>
    <title><literal>mp::RouterChain</literal>
     (<filename>router_chain.cpp</filename>)</title>
    <para>
     ### to be written
    </para>
   </section>

   <section>
    <title><literal>mp::RouterFleXML</literal>
     (<filename>router_flexml.cpp</filename>)</title>
    <para>
     ### to be written
    </para>
   </section>

   <section>
    <title><literal>mp::Session</literal>
     (<filename>session.cpp</filename>)</title>
    <para>
     ### to be written
    </para>
   </section>

   <section>
    <title><literal>mp::ThreadPoolSocketObserver</literal>
     (<filename>thread_pool_observer.cpp</filename>)</title>
    <para>
     ### to be written
    </para>
   </section>

   <section>
    <title><literal>mp::util</literal>
     (<filename>util.cpp</filename>)</title>
    <para>
     A namespace of various small utility functions and classes,
     collected together for convenience.  Most importantly, includes
     the <literal>mp::util::odr</literal> class, a wrapper for YAZ's
     ODR facilities.
    </para>
   </section>

   <section>
    <title><literal>mp::xml</literal>
     (<filename>xmlutil.cpp</filename>)</title>
    <para>
     A namespace of various XML utility functions and classes,
     collected together for convenience.
    </para>
   </section>
  </section>


  <section id="other.source.files">
   <title>Other Source Files</title>
   <para>
    In addition to the Metaproxy source files that define the classes
    described above, there are a few additional files which are
    briefly described here:
   </para>
   <variablelist>
    <varlistentry>
     <term><literal>metaproxy_prog.cpp</literal></term>
     <listitem>
      <para>
       The main function of the <command>metaproxy</command> program.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>ex_router_flexml.cpp</literal></term>
     <listitem>
      <para>
       Identical to <literal>metaproxy_prog.cpp</literal>: it's not clear why.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>test_*.cpp</literal></term>
     <listitem>
      <para>
       Unit-tests for various modules.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    ### Still to be described:
    <literal>ex_filter_frontend_net.cpp</literal>,
    <literal>filter_dl.cpp</literal>,
    <literal>plainfile.cpp</literal>,
    <literal>tstdl.cpp</literal>.
   </para>
  </section>
 </chapter>



 <chapter id="refguide">
  <title>Reference guide</title>
  <para>
   The material in this chapter is drawn directly from the individual
   manual entries.  In particular, the Metaproxy invocation section is
   available using <command>man metaproxy</command>, and the section
   on each individual filter is available using the name of the filter
   as the argument to the <command>man</command> command.
  </para>


  <section id="progref">
   <title>Metaproxy invocation</title>
   &progref;
  </section>


  <section id="filterref">
   <title>Reference guide to Metaproxy filters</title>
   &manref;
  </section>
 </chapter>



 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document: "main.xml"
 sgml-local-catalogs: nil
 sgml-namecase-general:t
 End:
 -->