-->
<!NOTATION PDF SYSTEM "PDF">
]>
-<!-- $Id: book.xml,v 1.37 2006-09-07 10:00:43 adam Exp $ -->
+<!-- $Id: book.xml,v 1.41 2006-10-12 11:34:07 marc Exp $ -->
<book id="metaproxy">
<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>
<author>
<firstname>Marc</firstname><surname>Cromme</surname>
</author>
+ <author>
+ <firstname>Mike</firstname><surname>Taylor</surname>
+ </author>
<copyright>
<year>2006</year>
<holder>Index Data ApS</holder>
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>
<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>
</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
+ recieved 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 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
projects / metaproxy-moved-to-github.git / blobdiff