Added id attribute for some sections so that our HTML/TKL pages
[metaproxy-moved-to-github.git] / doc / book.xml
1 <!-- $Id: book.xml,v 1.10 2006-04-20 12:42:47 adam Exp $ -->
2  <bookinfo>
3   <title>Metaproxy - User's Guide and Reference</title>
4   <author>
5    <firstname>Mike</firstname><surname>Taylor</surname>
6   </author>
7   <author>
8    <firstname>Adam</firstname><surname>Dickmeiss</surname>
9   </author>
10   <copyright>
11    <year>2006</year>
12    <holder>Index Data</holder>
13   </copyright>
14   <abstract>
15    <simpara>
16     Metaproxy is a universal router, proxy and encapsulated
17     metasearcher for information retrieval protocols.  It accepts,
18     processes, interprets and redirects requests from IR clients using
19     standard protocols such as ANSI/NISO Z39.50 (and in the future SRU
20     and SRW), as well as functioning as a limited
21     HTTP server.  Metaproxy is configured by an XML file which
22     specifies how the software should function in terms of routes that
23     the request packets can take through the proxy, each step on a
24     route being an instantiation of a filter.  Filters come in many
25     types, one for each operation: accepting Z39.50 packets, logging,
26     query transformation, multiplexing, etc.  Further filter-types can
27     be added as loadable modules to extend Metaproxy functionality,
28     using the filter API.
29    </simpara>
30    <simpara>
31     The terms under which Metaproxy will be distributed have yet to be
32     established, but it will not necessarily be open source; so users
33     should not at this stage redistribute the code without explicit
34     written permission from the copyright holders, Index Data ApS.
35    </simpara>
36   </abstract>
37  </bookinfo>
38
39  <chapter id="introduction">
40   <title>Introduction</title>
41   
42   
43    <para>
44     <ulink url="http://www.indexdata.com/metaproxy/">Metaproxy</ulink>
45     is a standalone program that acts as a universal router, proxy and
46     encapsulated metasearcher for information retrieval protocols such
47     as Z39.50, and in the future SRU and SRW.  To clients, it acts as a
48     server of these
49     protocols: it can be searched, records can be retrieved from it,
50     etc.  To servers, it acts as a client: it searches in them,
51     retrieves records from them, etc.  it satisfies its clients'
52     requests by transforming them, multiplexing them, forwarding them
53     on to zero or more servers, merging the results, transforming
54     them, and delivering them back to the client.  In addition, it
55     acts as a simple HTTP server; support for further protocols can be
56     added in a modular fashion, through the creation of new filters.
57    </para>
58    <screen>
59     Anything goes in!
60     Anything goes out!
61     Cold bananas, fish, pyjamas,
62     Mutton, beef and trout!
63         - attributed to Cole Porter.
64    </screen>
65    <para>
66     Metaproxy is a more capable alternative to
67     <ulink url="http://www.indexdata.com/yazproxy/">YAZ Proxy</ulink>,
68     being more powerful, flexible, configurable and extensible.  Among
69     its many advantages over the older, more pedestrian work are
70     support for multiplexing (encapsulated metasearching), routing by
71     database name, authentication and authorisation and serving local
72     files via HTTP.  Equally significant, its modular architecture
73     facilitites the creation of pluggable modules implementing further
74     functionality.
75    </para>
76  </chapter>
77
78
79
80  <chapter id="licence">
81   <title>The Metaproxy Licence</title>
82   <para>
83    <emphasis role="strong">
84      No decision has yet been made on the terms under which
85      Metaproxy will be distributed.
86    </emphasis>
87    It is possible that, unlike
88    other Index Data products, metaproxy may not be released under a
89    free-software licence such as the GNU GPL.  Until a decision is
90    made and a public statement made, then, and unless it has been
91    delivered to you other specific terms, please treat Metaproxy as
92    though it were proprietary software.
93    The code should not be redistributed without explicit
94    written permission from the copyright holders, Index Data ApS.
95   </para>
96  </chapter>
97
98
99
100  <chapter id="architecture">
101   <title>The Metaproxy Architecture</title>
102   <para>
103    The Metaproxy architecture is based on three concepts:
104    the <emphasis>package</emphasis>,
105    the <emphasis>route</emphasis>
106    and the <emphasis>filter</emphasis>.
107   </para>
108   <variablelist>
109    <varlistentry>
110     <term>Packages</term>
111     <listitem>
112      <para>
113       A package is request or response, encoded in some protocol,
114       issued by a client, making its way through Metaproxy, send to or
115       received from a server, or sent back to the client.
116      </para>
117      <para>
118       The core of a package is the protocol unit - for example, a
119       Z39.50 Init Request or Search Response, or an SRU searchRetrieve
120       URL or Explain Response.  In addition to this core, a package
121       also carries some extra information added and used by Metaproxy
122       itself.
123      </para>
124      <para>
125       In general, packages are doctored as they pass through
126       Metaproxy.  For example, when the proxy performs authentication
127       and authorisation on a Z39.50 Init request, it removes the
128       authentication credentials from the package so that they are not
129       passed onto the back-end server; and when search-response
130       packages are obtained from multiple servers, they are merged
131       into a single unified package that makes its way back to the
132       client.
133      </para>
134     </listitem>
135    </varlistentry>
136    <varlistentry>
137     <term>Routes</term>
138     <listitem>
139      <para>
140       Packages make their way through routes, which can be thought of
141       as programs that operate on the package data-type.  Each
142       incoming package initially makes its way through a default
143       route, but may be switched to a different route based on various
144       considerations.  Routes are made up of sequences of filters (see
145       below).
146      </para>
147     </listitem>
148    </varlistentry>
149    <varlistentry>
150     <term>Filters</term>
151     <listitem>
152      <para>
153       Filters provide the individual instructions within a route, and
154       effect the necessary transformations on packages.  A particular
155       configuration of Metaproxy is essentially a set of filters,
156       described by configuration details and arranged in order in one
157       or more routes.  There are many kinds of filter - about a dozen
158       at the time of writing with more appearing all the time - each
159       performing a specific function and configured by different
160       information.
161      </para>
162      <para>
163       The word ``filter'' is sometimes used rather loosely, in two
164       different ways: it may be used to mean a particular
165       <emphasis>type</emphasis> of filter, as when we speak of ``the
166       auth_simplefilter'' or ``the multi filter''; or it may be used
167       to be a specific <emphasis>instance</emphasis> of a filter
168       within a Metaproxy configuration.  For example, a single
169       configuration will often contain multiple instances of the
170       <literal>z3950_client</literal> filter.  In
171       operational terms, of these is a separate filter.  In practice,
172       context always make it clear which sense of the word ``filter''
173       is being used.
174      </para>
175      <para>
176       Extensibility of Metaproxy is primarily through the creation of
177       plugins that provide new filters.  The filter API is small and
178       conceptually simple, but there are many details to master.  See
179       the section below on
180       <link linkend="extensions">extensions</link>.
181      </para>
182     </listitem>
183    </varlistentry>
184   </variablelist>
185   <para>
186    Since packages are created and handled by the system itself, and
187    routes are conceptually simple, most of the remainder of this
188    document concentrates on filters.  After a brief overview of the
189    filter types follows, along with some thoughts on possible future
190    directions.
191   </para>
192  </chapter>
193
194
195
196  <chapter id="filters">
197   <title>Filters</title>
198   
199   
200   <section>
201    <title>Introductory notes</title>
202    <para>
203     It's useful to think of Metaproxy as an interpreter providing a small
204     number of primitives and operations, but operating on a very
205     complex data type, namely the ``package''.
206    </para>
207    <para>
208     A package represents a Z39.50 or SRU/W request (whether for Init,
209     Search, Scan, etc.)  together with information about where it came
210     from.  Packages are created by front-end filters such as
211     <literal>frontend_net</literal> (see below), which reads them from
212     the network; other front-end filters are possible.  They then pass
213     along a route consisting of a sequence of filters, each of which
214     transforms the package and may also have side-effects such as
215     generating logging.  Eventually, the route will yield a response,
216     which is sent back to the origin.
217    </para>
218    <para>
219     There are many kinds of filter: some that are defined statically
220     as part of Metaproxy, and others may be provided by third parties
221     and dynamically loaded.  They all conform to the same simple API
222     of essentially two methods: <function>configure()</function> is
223     called at startup time, and is passed a DOM tree representing that
224     part of the configuration file that pertains to this filter
225     instance: it is expected to walk that tree extracting relevant
226     information; and <function>process()</function> is called every
227     time the filter has to processes a package.
228    </para>
229    <para>
230     While all filters provide the same API, there are different modes
231     of functionality.  Some filters are sources: they create
232     packages
233     (<literal>frontend_net</literal>);
234     others are sinks: they consume packages and return a result
235     (<literal>z3950_client</literal>,
236     <literal>backend_test</literal>,
237     <literal>http_file</literal>);
238     the others are true filters, that read, process and pass on the
239     packages they are fed
240     (<literal>auth_simple</literal>,
241     <literal>log</literal>,
242     <literal>multi</literal>,
243     <literal>query_rewrite</literal>,
244     <literal>session_shared</literal>,
245     <literal>template</literal>,
246     <literal>virt_db</literal>).
247    </para>
248  </section>
249   
250   
251   <section id="overview.filter.types">
252    <title>Overview of filter types</title>
253    <para>
254     We now briefly consider each of the types of filter supported by
255     the core Metaproxy binary.  This overview is intended to give a
256     flavour of the available functionality; more detailed information
257     about each type of filter is included below in
258     <link linkend="filterref"
259           >the reference guide to Metaproxy filters</link>.
260    </para>
261    <para>
262     The filters are here named by the string that is used as the
263     <literal>type</literal> attribute of a
264     <literal>&lt;filter&gt;</literal> element in the configuration
265     file to request them, with the name of the class that implements
266     them in parentheses.  (The classname is not needed for normal
267     configuration and use of Metaproxy; it is useful only to
268     developers.)
269    </para>
270    <para>
271     The filters are here listed in alphabetical order:
272    </para>
273    
274    <section>
275     <title><literal>auth_simple</literal>
276      (mp::filter::AuthSimple)</title>
277     <para>
278      Simple authentication and authorisation.  The configuration
279      specifies the name of a file that is the user register, which
280      lists <varname>username</varname>:<varname>password</varname>
281      pairs, one per line, colon separated. When a session begins, it
282      is rejected unless username and passsword are supplied, and match
283      a pair in the register.  The configuration file may also specific
284      the name of another file that is the target register: this lists
285      lists <varname>username</varname>:<varname>dbname</varname>,<varname>dbname</varname>...
286      sets, one per line, with multiple database names separated by
287      commas.  When a search is processed, it is rejected unless the
288      database to be searched is one of those listed as available to
289      the user.
290     </para>
291    </section>
292    
293    <section>
294     <title><literal>backend_test</literal>
295     (mp::filter::Backend_test)</title>
296     <para>
297      A sink that provides dummy responses in the manner of the
298      <literal>yaz-ztest</literal> Z39.50 server.  This is useful only
299      for testing.  Seriously, you don't need this.  Pretend you didn't
300      even read this section.
301     </para>
302    </section>
303    
304    <section>
305     <title><literal>frontend_net</literal>
306      (mp::filter::FrontendNet)</title>
307     <para>
308      A source that accepts Z39.50 connections from a port
309      specified in the configuration, reads protocol units, and
310      feeds them into the next filter in the route.  When the result is
311      revceived, it is returned to the original origin.
312     </para>
313    </section>
314
315    <section>
316     <title><literal>http_file</literal>
317      (mp::filter::HttpFile)</title>
318     <para>
319      A sink that returns the contents of files from the local
320      filesystem in response to HTTP requests.  (Yes, Virginia, this
321      does mean that Metaproxy is also a Web-server in its spare time.  So
322      far it does not contain either an email-reader or a Lisp
323      interpreter, but that day is surely coming.)
324     </para>
325    </section>
326    
327    <section>
328     <title><literal>log</literal>
329      (mp::filter::Log)</title>
330     <para>
331      Writes logging information to standard output, and passes on
332      the package unchanged.
333    </para>
334    </section>
335    
336    <section>
337    <title><literal>multi</literal>
338      (mp::filter::Multi)</title>
339     <para>
340      Performs multicast searching.
341      See
342      <link linkend="multidb">the extended discussion</link>
343      of virtual databases and multi-database searching below.
344     </para>
345    </section>
346    
347    <section>
348    <title><literal>query_rewrite</literal>
349      (mp::filter::QueryRewrite)</title>
350     <para>
351      Rewrites Z39.50 Type-1 and Type-101 (``RPN'') queries by a
352      three-step process: the query is transliterated from Z39.50
353      packet structures into an XML representation; that XML
354      representation is transformed by an XSLT stylesheet; and the
355      resulting XML is transliterated back into the Z39.50 packet
356      structure.
357     </para>
358    </section>
359    
360    <section>
361     <title><literal>session_shared</literal>
362      (mp::filter::SessionShared)</title>
363     <para>
364      When this is finished, it will implement global sharing of
365      result sets (i.e. between threads and therefore between
366      clients), yielding performance improvements especially when
367      incoming requests are from a stateless environment such as a
368      web-server, in which the client process representing a session
369      might be any one of many.  However:
370     </para>
371     <warning>
372      <para>
373       This filter is not yet completed.
374      </para>
375     </warning>
376    </section>
377    
378    <section>
379     <title><literal>template</literal>
380      (mp::filter::Template)</title>
381     <para>
382      Does nothing at all, merely passing the packet on.  (Maybe it
383      should be called <literal>nop</literal> or
384      <literal>passthrough</literal>?)  This exists not to be used, but
385      to be copied - to become the skeleton of new filters as they are
386      written.  As with <literal>backend_test</literal>, this is not
387      intended for civilians.
388     </para>
389    </section>
390    
391    <section>
392     <title><literal>virt_db</literal>
393      (mp::filter::Virt_db)</title>
394     <para>
395      Performs virtual database selection: based on the name of the
396      database in the search request, a server is selected, and its
397      address added to the request in a <literal>VAL_PROXY</literal>
398      otherInfo packet.  It will subsequently be used by a
399      <literal>z3950_client</literal> filter.
400      See
401      <link linkend="multidb">the extended discussion</link>
402      of virtual databases and multi-database searching below.
403     </para>
404    </section>
405    
406    <section>
407     <title><literal>z3950_client</literal>
408      (mp::filter::Z3950Client)</title>
409     <para>
410      Performs Z39.50 searching and retrieval by proxying the
411      packages that are passed to it.  Init requests are sent to the
412      address specified in the <literal>VAL_PROXY</literal> otherInfo
413      attached to the request: this may have been specified by client,
414      or generated by a <literal>virt_db</literal> filter earlier in
415      the route.  Subsequent requests are sent to the same address,
416      which is remembered at Init time in a Session object.
417     </para>
418   </section>
419   </section>
420   
421   
422   <section id="future.directions">
423    <title>Future directions</title>
424   <para>
425     Some other filters that do not yet exist, but which would be
426     useful, are briefly described.  These may be added in future
427     releases (or may be created by third parties, as loadable
428     modules).
429    </para>
430
431    <variablelist>
432     <varlistentry>
433      <term><literal>frontend_cli</literal> (source)</term>
434     <listitem>
435       <para>
436        Command-line interface for generating requests.
437       </para>
438      </listitem>
439     </varlistentry>
440     <varlistentry>
441      <term><literal>frontend_sru</literal> (source)</term>
442      <listitem>
443       <para>
444        Receive SRU (and perhaps SRW) requests.
445      </para>
446      </listitem>
447     </varlistentry>
448     <varlistentry>
449      <term><literal>sru2z3950</literal> (filter)</term>
450      <listitem>
451       <para>
452        Translate SRU requests into Z39.50 requests.
453      </para>
454      </listitem>
455     </varlistentry>
456     <varlistentry>
457      <term><literal>sru_client</literal> (sink)</term>
458      <listitem>
459       <para>
460        SRU searching and retrieval.
461       </para>
462      </listitem>
463     </varlistentry>
464     <varlistentry>
465      <term><literal>srw_client</literal> (sink)</term>
466      <listitem>
467       <para>
468        SRW searching and retrieval.
469       </para>
470      </listitem>
471     </varlistentry>
472     <varlistentry>
473      <term><literal>opensearch_client</literal> (sink)</term>
474      <listitem>
475       <para>
476        A9 OpenSearch searching and retrieval.
477       </para>
478      </listitem>
479     </varlistentry>
480    </variablelist>
481   </section>
482  </chapter>
483  
484  
485  
486  <chapter id="configuration">
487   <title>Configuration: the Metaproxy configuration file format</title>
488   
489   
490   <section>
491    <title>Introductory notes</title>
492    <para>
493     If Metaproxy is an interpreter providing operations on packages, then
494     its configuration file can be thought of as a program for that
495     interpreter.  Configuration is by means of a single file, the name
496     of which is supplied as the sole command-line argument to the
497     <command>metaproxy</command> program.  (See
498     <link linkend="progref">the reference guide</link>
499     below for more information on invoking Metaproxy.)
500    </para>
501    <para>
502     The configuration files are written in XML.  (But that's just an
503     implementation detail - they could just as well have been written
504     in YAML or Lisp-like S-expressions, or in a custom syntax.)
505    </para>
506    <para>
507     Since XML has been chosen, an XML schema,
508     <filename>config.xsd</filename>, is provided for validating
509     configuration files.  This file is supplied in the
510     <filename>etc</filename> directory of the Metaproxy distribution.  It
511     can be used by (among other tools) the <command>xmllint</command>
512     program supplied as part of the <literal>libxml2</literal>
513     distribution:
514    </para>
515    <screen>
516     xmllint --noout --schema etc/config.xsd my-config-file.xml
517    </screen>
518    <para>
519     (A recent version of <literal>libxml2</literal> is required, as
520     support for XML Schemas is a relatively recent addition.)
521    </para>
522   </section>
523   
524   <section id="overview.xml.structure">
525    <title>Overview of XML structure</title>
526    <para>
527     All elements and attributes are in the namespace
528     <ulink url="http://indexdata.dk/yp2/config/1"/>.
529      This is most easily achieved by setting the default namespace on
530      the top-level element, as here:
531    </para>
532    <screen>
533     &lt;yp2 xmlns="http://indexdata.dk/yp2/config/1"&gt;
534    </screen>
535    <para>
536     The top-level element is &lt;yp2&gt;.  This contains a
537     &lt;start&gt; element, a &lt;filters&gt; element and a
538     &lt;routes&gt; element, in that order.  &lt;filters&gt; is
539     optional; the other two are mandatory.  All three are
540     non-repeatable.
541    </para>
542   <para>
543     The &lt;start&gt; element is empty, but carries a
544     <literal>route</literal> attribute, whose value is the name of
545     route at which to start running - analogous to the name of the
546     start production in a formal grammar.
547    </para>
548   <para>
549     If present, &lt;filters&gt; contains zero or more &lt;filter&gt;
550     elements.  Each filter carries a <literal>type</literal> attribute
551     which specifies what kind of filter is being defined
552     (<literal>frontend_net</literal>, <literal>log</literal>, etc.)
553     and contain various elements that provide suitable configuration
554     for a filter of its type.  The filter-specific elements are
555     described in
556     <link linkend="filterref">the reference guide below</link>.
557     Filters defined in this part of the file must carry an
558     <literal>id</literal> attribute so that they can be referenced
559     from elsewhere.
560    </para>
561    <para>
562     &lt;routes&gt; contains one or more &lt;route&gt; elements, each
563     of which must carry an <literal>id</literal> element.  One of the
564     routes must have the ID value that was specified as the start
565     route in the &lt;start&gt; element's <literal>route</literal>
566     attribute.  Each route contains zero or more &lt;filter&gt;
567     elements.  These are of two types.  They may be empty, but carry a
568     <literal>refid</literal> attribute whose value is the same as the
569     <literal>id</literal> of a filter previously defined in the
570     &lt;filters&gt; section.  Alternatively, a route within a filter
571     may omit the <literal>refid</literal> attribute, but contain
572     configuration elements similar to those used for filters defined
573     in the &lt;filters&gt; section.  (In other words, each filter in a
574     route may be included either by reference or by physical
575     inclusion.)
576    </para>
577   </section>
578
579
580   <section id="example.configuration">
581    <title>An example configuration</title>
582    <para>
583     The following is a small, but complete, Metaproxy configuration
584     file (included in the distribution as
585     <literal>metaproxy/etc/config0.xml</literal>).
586     This file defines a very simple configuration that simply proxies
587     to whatever backend server the client requests, but logs each
588     request and response.  This can be useful for debugging complex
589     client-server dialogues.
590    </para>
591    <screen><![CDATA[
592 <?xml version="1.0"?>
593 <yp2 xmlns="http://indexdata.dk/yp2/config/1">
594   <start route="start"/>
595   <filters>
596     <filter id="frontend" type="frontend_net">
597       <port>@:9000</port>
598     </filter>
599     <filter id="backend" type="z3950_client">
600     </filter>
601   </filters>
602   <routes>  
603     <route id="start">
604       <filter refid="frontend"/>
605       <filter type="log"/>
606       <filter refid="backend"/>
607     </route>
608   </routes>
609 </yp2>
610 ]]></screen>
611    <para>
612     It works by defining a single route, called
613     <literal>start</literal>, which consists of a sequence of three
614     filters.  The first and last of these are included by reference:
615     their <literal>&lt;filter&gt;</literal> elements have
616     <literal>refid</literal> attributes that refer to filters defined
617     within the prior <literal>&lt;filters&gt;</literal> section.  The
618     middle filter is included inline in the route.
619    </para>
620    <para>
621     The three filters in the route are as follows: first, a
622     <literal>frontend_net</literal> filter accepts Z39.50 requests
623     from any host on port 9000; then these requests are passed through
624     a <literal>log</literal> filter that emits a message for each
625     request; they are then fed into a <literal>z3950_client</literal>
626     filter, which forwards the requests to the client-specified
627     backend Z39.509 server.  When the response arrives, it is handed
628     back to the <literal>log</literal> filter, which emits another
629     message; and then to the front-end filter, which returns the
630     response to the client.
631    </para>
632   </section>
633  </chapter>
634
635
636
637  <chapter id="multidb">
638   <title>Virtual databases and multi-database searching</title>
639
640
641   <section>
642    <title>Introductory notes</title>
643    <para>
644     Two of Metaproxy's filters are concerned with multiple-database
645     operations.  Of these, <literal>virt_db</literal> can work alone
646     to control the routing of searches to one of a number of servers,
647     while <literal>multi</literal> can work with the output of
648     <literal>virt_db</literal> to perform multicast searching, merging
649     the results into a unified result-set.  The interaction between
650     these two filters is necessarily complex, reflecting the real
651     complexity of multicast searching in a protocol such as Z39.50
652     that separates initialisation from searching, with the database to
653     search known only during the latter operation.
654    </para>
655    <para>
656     ### Much, much more to say!
657    </para>
658   </section>
659  </chapter>
660
661
662
663  <chapter id="extensions">
664   <title>Writing extensions for Metaproxy</title>
665   <para>### To be written</para>
666  </chapter>
667
668
669
670
671  <chapter id="classes">
672   <title>Classes in the Metaproxy source code</title>
673
674
675   <section>
676    <title>Introductory notes</title>
677    <para>
678     <emphasis>Stop!  Do not read this!</emphasis>
679     You won't enjoy it at all.  You should just skip ahead to
680     <link linkend="refguide">the reference guide</link>,
681     which tells
682     <!-- The remainder of this paragraph is lifted verbatim from
683     Douglas Adams' _Hitch Hiker's Guide to the Galaxy_, chapter 8 -->
684     you things you really need to know, like the fact that the
685     fabulously beautiful planet Bethselamin is now so worried about
686     the cumulative erosion by ten billion visiting tourists a year
687     that any net imbalance between the amount you eat and the amount
688     you excrete whilst on the planet is surgically removed from your
689     bodyweight when you leave: so every time you go to the lavatory it
690     is vitally important to get a receipt.
691    </para>
692    <para>
693     This chapter contains documentation of the Metaproxy source code, and is
694     of interest only to maintainers and developers.  If you need to
695     change Metaproxy's behaviour or write a new filter, then you will most
696     likely find this chapter helpful.  Otherwise it's a waste of your
697     good time.  Seriously: go and watch a film or something.
698     <citetitle>This is Spinal Tap</citetitle> is particularly good.
699    </para>
700    <para>
701     Still here?  OK, let's continue.
702    </para>
703    <para>
704     In general, classes seem to be named big-endianly, so that
705     <literal>FactoryFilter</literal> is not a filter that filters
706     factories, but a factory that produces filters; and
707     <literal>FactoryStatic</literal> is a factory for the statically
708     registered filters (as opposed to those that are dynamically
709     loaded).
710    </para>
711   </section>
712
713   <section id="individual.classes">
714    <title>Individual classes</title>
715    <para>
716     The classes making up the Metaproxy application are here listed by
717     class-name, with the names of the source files that define them in
718     parentheses.
719    </para>
720
721    <section>
722     <title><literal>mp::FactoryFilter</literal>
723      (<filename>factory_filter.cpp</filename>)</title>
724     <para>
725      A factory class that exists primarily to provide the
726      <literal>create()</literal> method, which takes the name of a
727      filter class as its argument and returns a new filter of that
728      type.  To enable this, the factory must first be populated by
729      calling <literal>add_creator()</literal> for static filters (this
730      is done by the <literal>FactoryStatic</literal> class, see below)
731      and <literal>add_creator_dyn()</literal> for filters loaded
732      dynamically.
733     </para>
734    </section>
735
736    <section>
737     <title><literal>mp::FactoryStatic</literal>
738      (<filename>factory_static.cpp</filename>)</title>
739     <para>
740      A subclass of <literal>FactoryFilter</literal> which is
741      responsible for registering all the statically defined filter
742      types.  It does this by knowing about all those filters'
743      structures, which are listed in its constructor.  Merely
744      instantiating this class registers all the static classes.  It is
745      for the benefit of this class that <literal>struct
746       metaproxy_1_filter_struct</literal> exists, and that all the filter
747      classes provide a static object of that type.
748     </para>
749    </section>
750
751    <section>
752     <title><literal>mp::filter::Base</literal>
753      (<filename>filter.cpp</filename>)</title>
754     <para>
755      The virtual base class of all filters.  The filter API is, on the
756      surface at least, extremely simple: two methods.
757      <literal>configure()</literal> is passed a DOM tree representing
758      that part of the configuration file that pertains to this filter
759      instance, and is expected to walk that tree extracting relevant
760      information.  And <literal>process()</literal> processes a
761      package (see below).  That surface simplicitly is a bit
762      misleading, as <literal>process()</literal> needs to know a lot
763      about the <literal>Package</literal> class in order to do
764      anything useful.
765     </para>
766    </section>
767
768    <section>
769     <title><literal>mp::filter::AuthSimple</literal>,
770      <literal>Backend_test</literal>, etc.
771      (<filename>filter_auth_simple.cpp</filename>,
772      <filename>filter_backend_test.cpp</filename>, etc.)</title>
773     <para>
774      Individual filters.  Each of these is implemented by a header and
775      a source file, named <filename>filter_*.hpp</filename> and
776      <filename>filter_*.cpp</filename> respectively.  All the header
777      files should be pretty much identical, in that they declare the
778      class, including a private <literal>Rep</literal> class and a
779      member pointer to it, and the two public methods.  The only extra
780      information in any filter header is additional private types and
781      members (which should really all be in the <literal>Rep</literal>
782      anyway) and private methods (which should also remain known only
783      to the source file, but C++'s brain-damaged design requires this
784      dirty laundry to be exhibited in public.  Thanks, Bjarne!)
785     </para>
786     <para>
787      The source file for each filter needs to supply:
788     </para>
789     <itemizedlist>
790      <listitem>
791       <para>
792        A definition of the private <literal>Rep</literal> class.
793       </para>
794      </listitem>
795      <listitem>
796       <para>
797        Some boilerplate constructors and destructors.
798       </para>
799      </listitem>
800      <listitem>
801       <para>
802        A <literal>configure()</literal> method that uses the
803        appropriate XML fragment.
804       </para>
805      </listitem>
806      <listitem>
807       <para>
808        Most important, the <literal>process()</literal> method that
809        does all the actual work.
810       </para>
811      </listitem>
812     </itemizedlist>
813    </section>
814
815    <section>
816     <title><literal>mp::Package</literal>
817      (<filename>package.cpp</filename>)</title>
818     <para>
819      Represents a package on its way through the series of filters
820      that make up a route.  This is essentially a Z39.50 or SRU APDU
821      together with information about where it came from, which is
822      modified as it passes through the various filters.
823     </para>
824    </section>
825
826    <section>
827     <title><literal>mp::Pipe</literal>
828      (<filename>pipe.cpp</filename>)</title>
829     <para>
830      This class provides a compatibility layer so that we have an IPC
831      mechanism that works the same under Unix and Windows.  It's not
832      particularly exciting.
833     </para>
834    </section>
835
836    <section>
837     <title><literal>mp::RouterChain</literal>
838      (<filename>router_chain.cpp</filename>)</title>
839     <para>
840      ### to be written
841     </para>
842    </section>
843
844    <section>
845     <title><literal>mp::RouterFleXML</literal>
846      (<filename>router_flexml.cpp</filename>)</title>
847     <para>
848      ### to be written
849     </para>
850    </section>
851
852    <section>
853     <title><literal>mp::Session</literal>
854      (<filename>session.cpp</filename>)</title>
855     <para>
856      ### to be written
857     </para>
858    </section>
859
860    <section>
861     <title><literal>mp::ThreadPoolSocketObserver</literal>
862      (<filename>thread_pool_observer.cpp</filename>)</title>
863     <para>
864      ### to be written
865     </para>
866    </section>
867
868    <section>
869     <title><literal>mp::util</literal>
870      (<filename>util.cpp</filename>)</title>
871     <para>
872      A namespace of various small utility functions and classes,
873      collected together for convenience.  Most importantly, includes
874      the <literal>mp::util::odr</literal> class, a wrapper for YAZ's
875      ODR facilities.
876     </para>
877    </section>
878
879    <section>
880     <title><literal>mp::xml</literal>
881      (<filename>xmlutil.cpp</filename>)</title>
882     <para>
883      A namespace of various XML utility functions and classes,
884      collected together for convenience.
885     </para>
886    </section>
887   </section>
888
889
890   <section id="other.source.files">
891    <title>Other Source Files</title>
892    <para>
893     In addition to the Metaproxy source files that define the classes
894     described above, there are a few additional files which are
895     briefly described here:
896    </para>
897    <variablelist>
898     <varlistentry>
899      <term><literal>metaproxy_prog.cpp</literal></term>
900      <listitem>
901       <para>
902        The main function of the <command>metaproxy</command> program.
903       </para>
904      </listitem>
905     </varlistentry>
906     <varlistentry>
907      <term><literal>ex_router_flexml.cpp</literal></term>
908      <listitem>
909       <para>
910        Identical to <literal>metaproxy_prog.cpp</literal>: it's not clear why.
911       </para>
912      </listitem>
913     </varlistentry>
914     <varlistentry>
915      <term><literal>test_*.cpp</literal></term>
916      <listitem>
917       <para>
918        Unit-tests for various modules.
919       </para>
920      </listitem>
921     </varlistentry>
922    </variablelist>
923    <para>
924     ### Still to be described:
925     <literal>ex_filter_frontend_net.cpp</literal>,
926     <literal>filter_dl.cpp</literal>,
927     <literal>plainfile.cpp</literal>,
928     <literal>tstdl.cpp</literal>.
929    </para>
930   </section>
931  </chapter>
932
933
934
935  <chapter id="refguide">
936   <title>Reference guide</title>
937   <para>
938    The material in this chapter is drawn directly from the individual
939    manual entries.  In particular, the Metaproxy invocation section is
940    available using <command>man metaproxy</command>, and the section
941    on each individual filter is available using the name of the filter
942    as the argument to the <command>man</command> command.
943   </para>
944
945
946   <section id="progref">
947    <title>Metaproxy invocation</title>
948    &progref;
949   </section>
950
951
952   <section id="filterref">
953    <title>Reference guide to Metaproxy filters</title>
954    &manref;
955   </section>
956  </chapter>
957
958
959
960  <!-- Keep this comment at the end of the file
961  Local variables:
962  mode: sgml
963  sgml-omittag:t
964  sgml-shorttag:t
965  sgml-minimize-attributes:nil
966  sgml-always-quote-attributes:t
967  sgml-indent-step:1
968  sgml-indent-data:t
969  sgml-parent-document: "main.xml"
970  sgml-local-catalogs: nil
971  sgml-namecase-general:t
972  nxml-child-indent: 1
973  End:
974  -->