-->
<!NOTATION PDF SYSTEM "PDF">
]>
-<!-- $Id: book.xml,v 1.37 2006-09-07 10:00:43 adam Exp $ -->
+<!-- $Id: book.xml,v 1.38 2006-09-08 14:12:28 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
<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>
<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>
<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>
</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
--- /dev/null
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
+ <!ENTITY copyright SYSTEM "copyright.xml">
+]>
+<!-- $Id: bounce.xml,v 1.1 2006-09-08 14:12:28 marc Exp $ -->
+<refentry>
+ <refmeta>
+ <refentrytitle>bounce</refentrytitle>
+ <manvolnum>3mp</manvolnum>
+ <refmiscinfo>Metaproxy Module</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bounce</refname>
+ <refpurpose>bouncing package sink for all kind of metaproxy packages</refpurpose>
+ </refnamediv>
+
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ A sink that swallows all packages, 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 added at the end of
+ filter routes to prevent infinite hanging of yet unprocessed
+ packages. When a package is bounced, the client connection is
+ closed as well.
+ </para>
+ </refsect1>
+
+ <refsect1><title>EXAMPLES</title>
+ <para>
+ A typical configuration looks like this:
+ <screen><![CDATA[
+ <filter type="bounce"/>
+]]>
+ </screen>
+ </para>
+ </refsect1>
+
+ <refsect1><title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>metaproxy</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+ ©right;
+</refentry>
+
+<!-- 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:nil
+sgml-local-catalogs: nil
+sgml-namecase-general:t
+End:
+-->
projects / metaproxy-moved-to-github.git / commitdiff