Much new material, lots of cleaning up, etc.

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

<!-- $Id: book.xml,v 1.6 2006-04-19 15:43:40 mike 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</holder>
  </copyright>
  <abstract>
   <simpara>
    Metaproxy is a universal Z39.50/SRU router, proxy and encapsulated
    metasearcher.  It accepts, processes, interprets and redirects
    requests from IR clients using standard protocols such as
    ANSI/NISO Z39.50, SRU and SRW, as well as functioning as a limited
    HTTP 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>
  </abstract>
 </bookinfo>

 <chapter id="introduction">
  <title>Introduction</title>
  
  
   <para>
    <ulink url="http://indexdata.dk/metaproxy/">Metaproxy</ulink>
    is a standalone program that acts as a universal router, proxy and
    encapsulated metasearcher for information retrieval protocols such
    as Z39.50 and SRU/SRW.  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 HTTP server; support for further protocols can be
    added in a module fashion, through the creation of new filters.
   </para>
   <screen>
    Anything goes in!
    Anything goes out!
    Cold bananas, fish, pyjamas,
    Mutton, beef and trout!
        - attributed to Cole Porter.
   </screen>
   <para>
    Metaproxy is a more capable alternative to
    <ulink url="http://indexdata.dk/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>
 </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="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 SRW/U 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>
   <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 the Module
    Reference.
   </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 and SRW 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 multicast 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>
   <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>srw2z3950</literal> (filter)</term>
     <listitem>
      <para>
       Translate SRW requests into Z39.50 requests.
     </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>srw_client</literal> (sink)</term>
     <listitem>
      <para>
       SRW searching and retrieval.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>sru_client</literal> (sink)</term>
     <listitem>
      <para>
       SRU 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="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 with the output of
    <literal>virt_db</literal> to perform multicast searching, merging
    the results into a unified result-set.  The interaction between
    these two filters is necessarily complex, reflecting the real
    complexity of multicast searching in a protocol such as Z39.50
    that separates initialisation from searching, with the database to
    search known only during the latter operation.
   </para>
   <para>
    ### Much, much more to say!
   </para>
  </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>yp2</command> program.
   </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>
   <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 - analogouse 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; filters carry a <literal>type</literal> attribute and
    contain various elements that provide suitable configuration for
    filters of that type.  The filter-specific elements are described
    below.  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.
   </para>
  </section>


  <section>
   <title>Filter configuration</title>
   <para>
    All &lt;filter&gt; elements have in common that they must carry a
    <literal>type</literal> attribute whose value is one of the
    supported ones, listed in the schema file and discussed below.  In
    additional, &lt;filters&gt;s occurring the &lt;filters&gt; section
    must have an <literal>id</literal> attribute, and those occurring
    within a route must have either a <literal>refid</literal>
    attribute referencing a previously defined filter or contain its
    own configuration information.
   </para>
   <para>
    In general, each filter recognises different configuration
    elements within its element, as each filter has different
    functionality.  These are as follows:
   </para>

   <section>
    <title><literal>auth_simple</literal></title>
    <screen>
     &lt;filter type="auth_simple"&gt;
     &lt;userRegister&gt;../etc/example.simple-auth&lt;/userRegister&gt;
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>backend_test</literal></title>
    <screen>
     &lt;filter type="backend_test"/&gt;
    </screen>
   </section>

   <section>
    <title><literal>frontend_net</literal></title>
    <screen>
     &lt;filter type="frontend_net"&gt;
     &lt;threads&gt;10&lt;/threads&gt;
     &lt;port&gt;@:9000&lt;/port&gt;
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>http_file</literal></title>
    <screen>
     &lt;filter type="http_file"&gt;
     &lt;mimetypes&gt;/etc/mime.types&lt;/mimetypes&gt;
     &lt;area&gt;
     &lt;documentroot&gt;.&lt;/documentroot&gt;
     &lt;prefix&gt;/etc&lt;/prefix&gt;
     &lt;/area&gt;
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>log</literal></title>
    <screen>
     &lt;filter type="log"&gt;
     &lt;message&gt;B&lt;/message&gt;
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>multi</literal></title>
    <screen>
     &lt;filter type="multi"/&gt;
    </screen>
   </section>

   <section>
    <title><literal>query_rewrite</literal></title>
    <screen>
     &lt;filter type="query_rewrite"&gt;
     &lt;xslt&gt;pqf2pqf.xsl&lt;/xslt&gt;
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>session_shared</literal></title>
    <screen>
     &lt;filter type="session_shared"&gt;
     ### Not yet defined
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>template</literal></title>
    <screen>
     &lt;filter type="template"/&gt;
    </screen>
   </section>

   <section>
    <title><literal>virt_db</literal></title>
    <screen>
     &lt;filter type="virt_db"&gt;
     &lt;virtual&gt;
     &lt;database&gt;loc&lt;/database&gt;
     &lt;target&gt;z3950.loc.gov:7090/voyager&lt;/target&gt;
     &lt;/virtual&gt;
     &lt;virtual&gt;
     &lt;database&gt;idgils&lt;/database&gt;
     &lt;target&gt;indexdata.dk/gils&lt;/target&gt;
     &lt;/virtual&gt;
     &lt;/filter&gt;
    </screen>
   </section>

   <section>
    <title><literal>z3950_client</literal></title>
    <screen>
     &lt;filter type="z3950_client"&gt;
     &lt;timeout&gt;30&lt;/timeout&gt;
     &lt;/filter&gt;
    </screen>
   </section>
  </section>
 </chapter>



 <chapter id="moduleref">
  <title>Module Reference</title>
  <para>
   The material in this chapter includes the man pages material
  </para>
  &manref;
 </chapter>

 <chapter id="extensions">
  <title>Writing extensions for Metaproxy</title>
  <para>###</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.
   </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>
   <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
      yp2_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>
     ###
    </para>
   </section>

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

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

   <section>
    <title><literal>mp::ThreadPoolSocketObserver</literal>
     (<filename>thread_pool_observer.cpp</filename>)</title>
    <para>
     ###
    </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>
   <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>yp2</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>
   
   
   <!-- Epilogue -->
   <para>
    --
   </para>
   <screen>
    <!-- This is just a lame way to get some vertical whitespace at
    the end of the document -->
    
    
    
    
   </screen>
  </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
 nxml-child-indent: 1
 End:
 -->