+ <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 SRU/W 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 id="overview.filter.types">
+ <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
+ <link linkend="filterref"
+ >the reference guide to Metaproxy filters</link>.
+ </para>
+ <para>
+ The filters are here named by the string that is used as the
+ <literal>type</literal> attribute of a
+ <literal><filter></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 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 multi-database 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>