-->
<!NOTATION PDF SYSTEM "PDF">
]>
-<!-- $Id: book.xml,v 1.35 2006-06-21 15:08:58 mike Exp $ -->
+<!-- $Id: book.xml,v 1.39 2006-10-12 08:27:35 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>
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>template</literal>,
<literal>virt_db</literal>).
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>
<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>
<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 honour, and transforming
+ the present syntax and elementset name according to the rules
+ specified, to fetch only exisitng record formats, and transform
+ them on the fly to requested record syntaxes.
+ </para>
+ </section>
+
<section>
<title><literal>session_shared</literal>
(mp::filter::SessionShared)</title>
<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 defitely 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 pathes
+ <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>
<filter type="z3950_client">
<timeout>30</timeout>
</filter>
+ <filter type="bounce"/>
</route>
</routes>
</yp2>]]></screen>
<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
</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
projects / metaproxy-moved-to-github.git / blobdiff