From 4f8873c1f52ae189e60d4bc2f0ec30fa90f02ce5 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Thu, 20 Apr 2006 11:11:41 +0000 Subject: [PATCH] Many, many changes: new sections, reordering, clarification, add examples, steal Douglas Adams quote, etc. --- doc/book.xml | 328 +++++++++++++++++++++++++--------------------------------- 1 file changed, 139 insertions(+), 189 deletions(-) diff --git a/doc/book.xml b/doc/book.xml index 21f0ac7..915f69d 100644 --- a/doc/book.xml +++ b/doc/book.xml @@ -1,4 +1,4 @@ - + Metaproxy - User's Guide and Reference @@ -41,7 +41,7 @@ - Metaproxy + Metaproxy is a standalone program that acts as a universal router, proxy and encapsulated metasearcher for information retrieval protocols such as Z39.50, and in the future SRU and SRW. To clients, it acts as a @@ -53,7 +53,7 @@ on to zero or more servers, merging the results, transforming them, and delivering them back to the client. In addition, it acts as a simple HTTP server; support for further protocols can be - added in a module fashion, through the creation of new filters. + added in a modular fashion, through the creation of new filters. Anything goes in! @@ -64,7 +64,7 @@ Metaproxy is a more capable alternative to - YAZ Proxy, + YAZ Proxy, being more powerful, flexible, configurable and extensible. Among its many advantages over the older, more pedestrian work are support for multiplexing (encapsulated metasearching), routing by @@ -254,8 +254,9 @@ 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 the Module - Reference. + about each type of filter is included below in + the reference guide to Metaproxy filters. The filters are here named by the string that is used as the @@ -482,32 +483,6 @@ - - Virtual databases and multi-database searching - - -
- Introductory notes - - Two of Metaproxy's filters are concerned with multiple-database - operations. Of these, virt_db can work alone - to control the routing of searches to one of a number of servers, - while multi can work with the output of - virt_db to perform multicast searching, merging - the results into a unified result-set. The interaction between - these two filters is necessarily complex, reflecting the real - complexity of multicast searching in a protocol such as Z39.50 - that separates initialisation from searching, with the database to - search known only during the latter operation. - - - ### Much, much more to say! - -
- - - - Configuration: the Metaproxy configuration file format @@ -519,7 +494,9 @@ its configuration file can be thought of as a program for that interpreter. Configuration is by means of a single file, the name of which is supplied as the sole command-line argument to the - yp2 program. + metaproxy program. (See + the reference guide + below for more information on invoking Metaproxy.) The configuration files are written in XML. (But that's just an @@ -565,15 +542,19 @@ The <start> element is empty, but carries a route attribute, whose value is the name of - route at which to start running - analogouse to the name of the + route at which to start running - analogous to the name of the start production in a formal grammar. If present, <filters> contains zero or more <filter> - elements; filters carry a type attribute and - contain various elements that provide suitable configuration for - filters of that type. The filter-specific elements are described - below. Filters defined in this part of the file must carry an + elements. Each filter carries a type attribute + which specifies what kind of filter is being defined + (frontend_net, log, etc.) + and contain various elements that provide suitable configuration + for a filter of its type. The filter-specific elements are + described in + the reference guide below. + Filters defined in this part of the file must carry an id attribute so that they can be referenced from elsewhere. @@ -589,159 +570,104 @@ <filters> section. Alternatively, a route within a filter may omit the refid attribute, but contain configuration elements similar to those used for filters defined - in the <filters> section. + in the <filters> section. (In other words, each filter in a + route may be included either by reference or by physical + inclusion.)
- Filter configuration + An example configuration + + The following is a small, but complete, Metaproxy configuration + file (included in the distribution as + metaproxy/etc/config0.xml). + This file defines a very simple configuration that simply proxies + to whatever backend server the client requests, but logs each + request and response. This can be useful for debugging complex + client-server dialogues. + + + + + + + @:9000 + + + + + + + + + + + + +]]> - All <filter> elements have in common that they must carry a - type attribute whose value is one of the - supported ones, listed in the schema file and discussed below. In - additional, <filters>s occurring the <filters> section - must have an id attribute, and those occurring - within a route must have either a refid - attribute referencing a previously defined filter or contain its - own configuration information. + It works by defining a single route, called + start, which consists of a sequence of three + filters. The first and last of these are included by reference: + their <filter> elements have + refid attributes that refer to filters defined + within the prior <filters> section. The + middle filter is included inline in the route. - In general, each filter recognises different configuration - elements within its element, as each filter has different - functionality. These are as follows: + The three filters in the route are as follows: first, a + frontend_net filter accepts Z39.50 requests + from any host on port 9000; then these requests are passed through + a log filter that emits a message for each + request; they are then fed into a z3950_client + filter, which forwards the requests to the client-specified + backend Z39.509 server. When the response arrives, it is handed + back to the log filter, which emits another + message; and then to the front-end filter, which returns the + response to the client. +
+ -
- <literal>auth_simple</literal> - - <filter type="auth_simple"> - <userRegister>../etc/example.simple-auth</userRegister> - </filter> - -
- -
- <literal>backend_test</literal> - - <filter type="backend_test"/> - -
- -
- <literal>frontend_net</literal> - - <filter type="frontend_net"> - <threads>10</threads> - <port>@:9000</port> - </filter> - -
- -
- <literal>http_file</literal> - - <filter type="http_file"> - <mimetypes>/etc/mime.types</mimetypes> - <area> - <documentroot>.</documentroot> - <prefix>/etc</prefix> - </area> - </filter> - -
- -
- <literal>log</literal> - - <filter type="log"> - <message>B</message> - </filter> - -
- -
- <literal>multi</literal> - - <filter type="multi"/> - -
-
- <literal>query_rewrite</literal> - - <filter type="query_rewrite"> - <xslt>pqf2pqf.xsl</xslt> - </filter> - -
-
- <literal>session_shared</literal> - - <filter type="session_shared"> - ### Not yet defined - </filter> - -
- -
- <literal>template</literal> - - <filter type="template"/> - -
+ + Virtual databases and multi-database searching -
- <literal>virt_db</literal> - - <filter type="virt_db"> - <virtual> - <database>loc</database> - <target>z3950.loc.gov:7090/voyager</target> - </virtual> - <virtual> - <database>idgils</database> - <target>indexdata.dk/gils</target> - </virtual> - </filter> - -
-
- <literal>z3950_client</literal> - - <filter type="z3950_client"> - <timeout>30</timeout> - </filter> - -
+
+ Introductory notes + + Two of Metaproxy's filters are concerned with multiple-database + operations. Of these, virt_db can work alone + to control the routing of searches to one of a number of servers, + while multi can work with the output of + virt_db to perform multicast searching, merging + the results into a unified result-set. The interaction between + these two filters is necessarily complex, reflecting the real + complexity of multicast searching in a protocol such as Z39.50 + that separates initialisation from searching, with the database to + search known only during the latter operation. + + + ### Much, much more to say! +
- - Metaproxy invocation - - The material in this chapter includes the man pages material. - - &progref; - - - - Reference guide to Metaproxy filters - - The material in this chapter includes the man pages material. - - &manref; - - Writing extensions for Metaproxy - ### + ### To be written + + + Classes in the Metaproxy source code @@ -750,7 +676,18 @@ Introductory notes Stop! Do not read this! - You won't enjoy it at all. + You won't enjoy it at all. You should just skip ahead to + the reference guide, + which tells + + you things you really need to know, like the fact that the + fabulously beautiful planet Bethselamin is now so worried about + the cumulative erosion by ten billion visiting tourists a year + that any net imbalance between the amount you eat and the amount + you excrete whilst on the planet is surgically removed from your + bodyweight when you leave: so every time you go to the lavatory it + is vitally important to get a receipt. This chapter contains documentation of the Metaproxy source code, and is @@ -806,7 +743,7 @@ structures, which are listed in its constructor. Merely instantiating this class registers all the static classes. It is for the benefit of this class that struct - yp2_filter_struct exists, and that all the filter + metaproxy_1_filter_struct exists, and that all the filter classes provide a static object of that type. @@ -900,7 +837,7 @@ <literal>mp::RouterChain</literal> (<filename>router_chain.cpp</filename>) - ### + ### to be written @@ -908,7 +845,7 @@ <literal>mp::RouterFleXML</literal> (<filename>router_flexml.cpp</filename>) - ### + ### to be written @@ -916,7 +853,7 @@ <literal>mp::Session</literal> (<filename>session.cpp</filename>) - ### + ### to be written @@ -924,7 +861,7 @@ <literal>mp::ThreadPoolSocketObserver</literal> (<filename>thread_pool_observer.cpp</filename>) - ### + ### to be written @@ -962,7 +899,7 @@ metaproxy_prog.cpp - The main function of the yp2 program. + The main function of the metaproxy program. @@ -990,23 +927,36 @@ plainfile.cpp, tstdl.cpp. - - - - - -- - - - - - - - - + + + + Reference guide + + The material in this chapter is drawn directly from the individual + manual entries. In particular, the Metaproxy invocation section is + available using man metaproxy, and the section + on each individual filter is available using the name of the filter + as the argument to the man command. + + + +
+ Metaproxy invocation + &progref; +
+ + +
+ Reference guide to Metaproxy filters + &manref; +
+ + + +