-<!-- $Id: book.xml,v 1.24 2006-04-27 16:16:28 mike Exp $ -->
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+[
+ <!ENTITY local SYSTEM "local.ent">
+ <!ENTITY manref SYSTEM "manref.xml">
+ <!ENTITY progref SYSTEM "progref.xml">
+ <!ENTITY % common SYSTEM "common/common.ent">
+ %common;
+ <!-- Next line allows imagedata/@format="PDF" and is taken from
+ http://lists.oasis-open.org/archives/docbook/200303/msg00163.html
+ -->
+ <!ENTITY % local.notation.class "| PDF">
+ <!-- Next line is necessary for some XML parsers, for reasons I
+ don't understand. I got this from
+ http://lists.oasis-open.org/archives/docbook/200303/msg00180.html
+ -->
+ <!NOTATION PDF SYSTEM "PDF">
+]>
+<!-- $Id: book.xml,v 1.42 2006-10-12 11:52:24 marc Exp $ -->
+<book id="metaproxy">
<bookinfo>
<title>Metaproxy - User's Guide and Reference</title>
<author>
- <firstname>Mike</firstname><surname>Taylor</surname>
+ <firstname>Adam</firstname><surname>Dickmeiss</surname>
</author>
<author>
- <firstname>Adam</firstname><surname>Dickmeiss</surname>
+ <firstname>Marc</firstname><surname>Cromme</surname>
+ </author>
+ <author>
+ <firstname>Mike</firstname><surname>Taylor</surname>
</author>
<copyright>
<year>2006</year>
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.
+ Metaproxy is <emphasis>not</emphasis> open-source software, but
+ may be freely downloaded, unpacked, inspected, built and run for
+ evaluation purposes. Deployment requires a separate, commercial,
+ license.
</simpara>
<simpara>
<inlinemediaobject>
<para>
<ulink url="&url.metaproxy;">Metaproxy</ulink>
- is a standalone program that acts as a universal router, proxy and
+ is a stand alone 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>.
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
+ database name, authentication and authorization 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
+ This manual will describe how to install Metaproxy
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
</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 id="license">
+ <title>The Metaproxy License</title>
+ <orderedlist numeration="arabic">
+ <listitem>
+ <para>
+ You are allowed to download this software for evaluation purposes.
+ You can unpack it, build it, run it, see how it works and how it fits
+ your needs, all at zero cost.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You may NOT deploy the software. For the purposes of this license,
+ deployment means running it for any purpose other than evaluation,
+ whether or not you or anyone else makes a profit from doing so. If
+ you wish to deploy the software, you must first contact Index Data and
+ arrange to purchase a DEPLOYMENT LICENCE. If you are unsure
+ whether or not your proposed use of the software constitutes
+ deployment, email us at <literal>info@indexdata.com</literal>
+ for clarification.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You may modify your copy of the software (fix bugs, add features)
+ if you need to. We encourage you to send your changes back to us for
+ integration into the master copy, but you are not obliged to do so. You
+ may NOT pass your changes on to any other party.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There is NO WARRANTY for this software, to the extent permitted by
+ applicable law. We provide the software ``as is'' without warranty of
+ any kind, either expressed or implied, including, but not limited to, the
+ implied warranties of MERCHANTABILITY and FITNESS FOR A
+ PARTICULAR PURPOSE. The entire risk as to the quality and
+ performance of the software is with you. Should the software prove
+ defective, you assume the cost of all necessary servicing, repair or
+ correction. In no event unless required by applicable law will we be
+ liable to you for damages, arising out of the use of the software,
+ including but not limited to loss of data or data being rendered
+ inaccurate.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All rights to the software are reserved by Index Data except where
+ this license explicitly says otherwise.
+ </para>
+ </listitem>
+ </orderedlist>
</chapter>
-
+
<chapter id="installation">
<title>Installation</title>
<para>
for more information.
</para>
<para>
- We have succesfully used Metaproxy with Boost using the compilers
+ We have successfully 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>
<section id="installation.debian">
- <title>Installation on Debian</title>
+ <title>Installation on Debian GNU/Linux</title>
<para>
- ### To be written
+ 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>
- </section>
+ <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.
+ Metaproxy can be compiled with Microsoft
+ <ulink url="&url.vstudio;">Visual Studio</ulink>.
+ Version 2003 (C 7.1) and 2005 (C 8.0) is known to work.
</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 this
- home page. The files download are called something like:
- <literal>boost_1_33-1.exe</literal>
+ 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
- <literal>boost-jam-3.1.12-1-ntx86.zip</literal>.
- Unpack Boost Jam first. Put <literal>bjam.exe</literal>
+ <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
+ For Visual Studio 2003, use
+ <screen>
+ bjam "-sTOOLS=vc-7_1"
+ </screen>
+ Here <literal>vc-7_1</literal> refers to a "Toolset" (compiler system).
+ For Visual Studio 2005, use
+ <screen>
+ bjam "-sTOOLS=vc-8_0"
+ </screen>
+ To install the libraries in a common place, use
+ <screen>
+ bjam "-sTOOLS=vc-7_1" install
+ </screen>
+ (or vc-8_0 for VS 2005).
+ </para>
+ <para>
+ By default, the Boost build process installs 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
+ For more information about installing Boost refer to the
<ulink url="&url.boost.getting.started;">getting started</ulink>
pages.
</para>
<ulink url="&url.libxml2.download.win32;">here</ulink>.
</para>
<para>
- Libxslt has other dependencies, but thes can all be downloaded
+ Libxslt has other dependencies, but these can all be downloaded
from the same site. Get the following:
iconv, zlib, libxml2, libxslt.
</para>
<section id="installation.windows.metaproxy">
<title>Metaproxy</title>
<para>
- Metaproxy is shipped with NMAKE makfiles as well - similar
+ Metaproxy is shipped with NMAKE makefiles 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>
+
+ <variablelist>
+ <varlistentry><term><literal>DEBUG</literal></term>
+ <listitem><para>
+ If set to 1, the software is
+ compiled with debugging libraries (code generation is
+ multi-threaded debug DLL).
+ If set to 0, the software is compiled with release libraries
+ (code generation is multi-threaded DLL).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BOOST</literal></term>
+ <listitem>
+ <para>
+ Boost install location
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BOOST_VERSION</literal></term>
+ <listitem>
+ <para>
+ Boost version (replace . with _).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BOOST_TOOLSET</literal></term>
+ <listitem>
+ <para>
+ Boost toolset.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>LIBXSLT_DIR</literal>,
+ <literal>LIBXML2_DIR</literal> ..</term>
+ <listitem>
+ <para>
+ Specify the locations of Libxslt, libiconv, libxml2 and
+ libxslt.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
<para>
- After succesful compilation you'll find
+ After successful compilation you'll find
<literal>metaproxy.exe</literal> in the
<literal>bin</literal> directory.
</para>
</section>
+
</section>
</chapter>
<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
+ and authorization 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
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
+ auth_simple filter'' 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
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
+ called at startup time, and is passed an XML 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
others are sinks: they consume packages and return a result
(<literal>z3950_client</literal>,
<literal>backend_test</literal>,
+ <literal>bounce</literal>,
<literal>http_file</literal>);
the others are true filters, that read, process and pass on the
packages they are fed
<literal>log</literal>,
<literal>multi</literal>,
<literal>query_rewrite</literal>,
+ <literal>record_transform</literal>,
<literal>session_shared</literal>,
+ <literal>sru_z3950</literal>,
<literal>template</literal>,
<literal>virt_db</literal>).
</para>
<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
+ flavor 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>.
The filters are here listed in alphabetical order:
</para>
+<!--
+
+### New filters:
+
+New virt_db-alike that does inteligent peer choice, explain merging,
+adds FD&N to explain. Keeps init responses (like "virt_db Classic"),
+makes routing choices based on local explain knowledge. Ref IDDI
+paper.
+
+Filter to convert Explain Classic to ZeeRex.
+
+CQL2PQF (which needs augmented ZeeRex) - MARC for Talis.
+
+SRU2Z39.50 (ditto).
+
+Figure out what additional information we need in:
+ ZeeRex (check against D3.1)
+ Init request (e.g. loop detection)
+ Query package (e.g. number of hops)
+ Query response (e.g. record source)
+
+-->
+
<section>
<title><literal>auth_simple</literal>
(mp::filter::AuthSimple)</title>
<para>
- Simple authentication and authorisation. The configuration
+ Simple authentication and authorization. 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
<title><literal>backend_test</literal>
(mp::filter::Backend_test)</title>
<para>
- A sink that provides dummy responses in the manner of the
+ A partial 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.
</section>
<section>
+ <title><literal>bounce</literal>
+ (mp::filter::Bounce)</title>
+ <para>
+ A sink that swallows <emphasis>all packages</emphasis>,
+ and returns them almost unprocessed.
+ It never sends any package of any type further down the row, but
+ sets Z39.50 packages to Z_Close, and HTTP_Request packages to
+ HTTP_Response err code 400 packages, and adds a suitable bounce
+ message.
+ The bounce filter is usually added at end of each filter chain
+ config.xml to prevent infinite hanging of for example HTTP
+ requests packages when only the Z39.50 client partial sink
+ filter is found in the
+ route.
+ </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.
+ received, it is returned to the original origin.
</para>
</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
+ A partial sink which swallows only HTTP_Request packages, and
+ returns the contents of files from the local
+ filesystem in response to HTTP requests.
+ It lets Z39.50 packages and all other forthcoming package types
+ pass untouched.
+ (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.)
(mp::filter::Log)</title>
<para>
Writes logging information to standard output, and passes on
- the package unchanged.
+ the package unchanged. A log file name can be specified, as well
+ as multiple different logging formats.
</para>
</section>
</para>
</section>
+
+ <section>
+ <title><literal>record_transform</literal>
+ (mp::filter::RecordTransform)</title>
+ <para>
+ This filter acts only on Z3950 present requests, and let all
+ other types of packages and requests pass untouched. It's use is
+ twofold: blocking Z3950 present requests, which the backend
+ server does not understand and can not honor, and transforming
+ the present syntax and elementset name according to the rules
+ specified, to fetch only existing record formats, and transform
+ them on the fly to requested record syntaxes.
+ </para>
+ </section>
+
<section>
<title><literal>session_shared</literal>
(mp::filter::SessionShared)</title>
</para>
</warning>
</section>
+
+ <section>
+ <title><literal>sru_z3950</literal>
+ (mp::filter::SRUtoZ3950)</title>
+ <para>
+ This filter transforms valid
+ SRU/GET or SRU/SOAP requests to Z3950 requests, and wraps the
+ received hit counts and XML records into suitable SRU response messages.
+ </para>
+ </section>
<section>
<title><literal>template</literal>
<section>
<title><literal>virt_db</literal>
- (mp::filter::Virt_db)</title>
+ (mp::filter::VirtualDB)</title>
<para>
Performs virtual database selection: based on the name of the
database in the search request, a server is selected, and its
<title><literal>z3950_client</literal>
(mp::filter::Z3950Client)</title>
<para>
- Performs Z39.50 searching and retrieval by proxying the
+ A partial sink which swallows only Z39.50 packages.
+ It 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.
+ HTTP_Request packages and all other forthcoming package types
+ are passed untouched.
</para>
</section>
</section>
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>
+ <title>Overview of the config file XML structure</title>
<para>
All elements and attributes are in the namespace
<ulink url="http://indexdata.dk/yp2/config/1"/>.
<para>
The following is a small, but complete, Metaproxy configuration
file (included in the distribution as
- <literal>metaproxy/etc/config0.xml</literal>).
+ <literal>metaproxy/etc/config1.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
<filter refid="frontend"/>
<filter type="log"/>
<filter refid="backend"/>
+ <filter type="bounce"/>
</route>
</routes>
</yp2>
]]></screen>
<para>
It works by defining a single route, called
- <literal>start</literal>, which consists of a sequence of three
+ <literal>start</literal>, which consists of a sequence of four
filters. The first and last of these are included by reference:
their <literal><filter></literal> elements have
<literal>refid</literal> attributes that refer to filters defined
middle filter is included inline in the route.
</para>
<para>
- The three filters in the route are as follows: first, a
+ The four 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
+ filter, which forwards all Z39.50 requests to the client-specified
+ back-end Z39.509 server. Those Z39.50 packages are returned by the
+ <literal>z3950_client</literal> filter, with the response data
+ filled by the external Z39.50 server targeted.
+ All non-Z39.50 packages are passed through to the
+ <literal>bounce</literal> filter, which definitely bounces
+ everything, including fish, bananas, cold pyjamas,
+ mutton, beef and trout packages.
+ 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.
+ message; and then to the <literal>frontend_net</literal> filter,
+ which returns the response to the client.
</para>
</section>
+ <section id="checking.xml.syntax">
+ <title>Config file syntax checking</title>
+ <para>
+ The distribution contains RelaxNG Compact and XML syntax checking
+ files, as well as XML Schema files. These are found in the
+ distribution paths
+ <screen>
+ xml/schema/metaproxy.rnc
+ xml/schema/metaproxy.rng
+ xml/schema/metaproxy.xsd
+ </screen>
+ and can be used to verify or debug the XML structure of
+ configuration files. For example, using the utility
+ <filename>xmllint</filename>, syntax checking is done like this:
+ <screen>
+ xmllint --noout --schema xml/schema/metaproxy.xsd etc/config-local.xml
+ xmllint --noout --relaxng xml/schema/metaproxy.rng etc/config-local.xml
+ </screen>
+ (A recent version of <literal>libxml2</literal> is required, as
+ support for XML Schemas is a relatively recent addition.)
+ </para>
+ <para>
+ You can of course use any other RelaxNG or XML Schema compliant tool
+ you wish.
+ </para>
+ </section>
</chapter>
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
+ as Z39.50 that separates initialization from searching, and in
+ which the database to be searched is not known at initialization
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
+ next two sections of this chapter are ``HOW-TO'' 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.
<filter type="z3950_client">
<timeout>30</timeout>
</filter>
+ <filter type="bounce"/>
</route>
</routes>
</yp2>]]></screen>
be metasearched in this way: issues of resource usage and
administrative complexity dictate the practical limits.
</para>
+ <para>
+ What happens when one of the databases doesn't respond? By default,
+ the entire multi-database search fails, and the appropriate
+ diagnostic is returned to the client. This is usually appropriate
+ during development, when technicians need maximum information, but
+ can be inconvenient in deployment, when users typically don't want
+ to be bothered with problems of this kind and prefer just to get
+ the records from the databases that are available. To obtain this
+ latter behavior add an empty
+ <literal><hideunavailable></literal>
+ element inside the
+ <literal>multi</literal> filter:
+ </para>
+ <screen><![CDATA[ <filter type="multi">
+ <hideunavailable/>
+ </filter>]]></screen>
+ <para>
+ Under this regime, an error is reported to the client only if
+ <emphasis>all</emphasis> the databases in a multi-database search
+ are unavailable.
+ </para>
</section>
>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.
+ Within Metaproxy, Search requests that are part of the same
+ session as an Init request that carries a
+ <literal>VAL_PROXY</literal> otherInfo are also annotated with the
+ same information. 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
+ 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
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>.
+ It is possible for a <literal>virt_db</literal> filter to contain
+ multiple
+ <literal><target></literal>
+ elements. What does this mean? Only that the filter will add
+ multiple <literal>VAL_PROXY</literal> otherInfo packets to the
+ Search requests that pass through it. That's because the virtual
+ DB filter is dumb, and does exactly what it's told - no more, no
+ less.
+ If a Search request with multiple <literal>VAL_PROXY</literal>
+ otherInfo packets reaches a <literal>z3950_client</literal>
+ filter, this is an error. That filter doesn't know how to deal
+ with multiple targets, so it will either just pick one and search
+ in it, or (better) fail with an error message.
+ </para>
+ <para>
+ The <literal>multi</literal> filter comes to the rescue! This is
+ the only filter that knows how to deal with multiple
+ <literal>VAL_PROXY</literal> otherInfo packets, and it does so by
+ making multiple copies of the entire Search request: one for each
+ <literal>VAL_PROXY</literal>. Each of these new copies is then
+ passed down through the remaining filters in the route. (The
+ copies are handled in parallel though the
+ spawning of new threads.) Since the copies each have only one
+ <literal>VAL_PROXY</literal> otherInfo, they can be handled by the
+ <literal>z3950_client</literal> filter, which happily deals with
+ each one individually. When the results of the individual
+ searches come back up to the <literal>multi</literal> filter, it
+ merges them into a single Search response, which is what
+ eventually makes it back to the client.
</para>
</section>
<simpara>
<inlinemediaobject>
<imageobject>
- <imagedata fileref="multi.pdf" format="PDF"/>
+ <imagedata fileref="multi.pdf" format="PDF" scale="50"/>
</imageobject>
<imageobject>
<imagedata fileref="multi.png" format="PNG"/>
[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.]
+ tool chain has not been able to include the diagram in this
+ document.]
</phrase>
</textobject>
<!-- ### This used to work with an older version of DocBook
<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
+ change Metaproxy's behavior 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>
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
+ <literal>configure()</literal> is passed an XML 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
+ package (see below). That surface simplicity 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.
<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!)
+ member pointer to it, and the two public methods.
</para>
<para>
The source file for each filter needs to supply:
</para>
</section>
</chapter>
-
-
-
- <chapter id="refguide">
+
+
+
+ <reference 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>
-
-
+ <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>
+ &manref;
+ </reference>
+</book>
<!-- Keep this comment at the end of the file
Local variables:
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
- sgml-parent-document: "main.xml"
+ sgml-parent-document: nil
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
projects / metaproxy-moved-to-github.git / blobdiff