X-Git-Url: http://lists.indexdata.com/cgi-bin?a=blobdiff_plain;f=doc%2Fbook.xml;h=ad11c218fc3f17929b86e71fdd890f8019ac3533;hb=4b5158c40900ee67ec56fc6933fb5cd2dcca72b9;hp=74bd70d8ebf80c30dbe1fdc49c6e8fe982160d08;hpb=f6df7b1cc4f4860d470577b283c2bbe216567517;p=metaproxy-moved-to-github.git
diff --git a/doc/book.xml b/doc/book.xml
index 74bd70d..ad11c21 100644
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -1,4 +1,4 @@
-
+
Metaproxy - User's Guide and Reference
@@ -13,7 +13,24 @@
- Metaproxy - universal Z39.50/SRU router, proxy and encapsulated metasearcher
+ Metaproxy is a universal Z39.50/SRU router, proxy and encapsulated
+ metasearcher. It accepts, processes, interprets and redirects
+ requests from IR clients using standard protocols such as
+ ANSI/NISO Z39.50, SRU and SRW, as well as functioning as a limited
+ HTTP server. Metaproxy is configured by an XML file which
+ specifies how the software should function in terms of routes that
+ the request packets can take through the proxy, each step on a
+ route being an instantiation of a filter. Filters come in many
+ types, one for each operation: accepting Z39.50 packets, logging,
+ query transformation, multiplexing, etc. Further filter-types can
+ be added as loadable modules to extend Metaproxy functionality,
+ using the filter API.
+
+
+ The terms under which Metaproxy will be distributed have yet to be
+ established, but it will not necessarily be open source; so users
+ should not at this stage redistribute the code without explicit
+ written permission from the copyright holders, Index Data ApS.
@@ -22,8 +39,6 @@
Introduction
-
- OverviewMetaproxy
is a standalone program that acts as a universal router, proxy and
@@ -34,8 +49,17 @@
retrieves records from them, etc. it satisfies its clients'
requests by transforming them, multiplexing them, forwarding them
on to zero or more servers, merging the results, transforming
- them, and delivering them back to the client.
+ 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.
+
+ Anything goes in!
+ Anything goes out!
+ Cold bananas, fish, pyjamas,
+ Mutton, beef and trout!
+ - attributed to Cole Porter.
+
Metaproxy is a more capable alternative to
YAZ Proxy,
@@ -47,7 +71,6 @@
facilitites the creation of pluggable modules implementing further
functionality.
-
@@ -65,6 +88,8 @@
made and a public statement made, then, and unless it has been
delivered to you other specific terms, please treat Metaproxy as
though it were proprietary software.
+ The code should not be redistributed without explicit
+ written permission from the copyright holders, Index Data ApS.
@@ -137,9 +162,10 @@
different ways: it may be used to mean a particular
type of filter, as when we speak of ``the
auth_simplefilter'' or ``the multi filter''; or it may be used
- to be a specific instance of a filter within a Metaproxy
- configuration. For example, a single configuration will often
- contain multiple instances of the z3950_client filter. In
+ to be a specific instance of a filter
+ within a Metaproxy configuration. For example, a single
+ configuration will often contain multiple instances of the
+ z3950_client filter. In
operational terms, of these is a separate filter. In practice,
context always make it clear which sense of the word ``filter''
is being used.
@@ -189,7 +215,7 @@
There are many kinds of filter: some that are defined statically
- as part of Metaproxy, and other that may be provided by third parties
+ 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: configure() is
called at startup time, and is passed a DOM tree representing that
@@ -221,13 +247,25 @@
- Individual filters
+ Overview of filter types
+
+ 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.
+
The filters are here named by the string that is used as the
type attribute of a
<filter> element in the configuration
file to request them, with the name of the class that implements
- them in parentheses.
+ them in parentheses. (The classname is not needed for normal
+ configuration and use of Metaproxy; it is useful only to
+ developers.)
+
+
+ The filters are here listed in alphabetical order:
@@ -239,10 +277,13 @@
lists username:password
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.
-
-
- ### discuss authorisation phase
+ a pair in the register. The configuration file may also specific
+ the name of another file that is the target register: this lists
+ lists username:dbname,dbname...
+ 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.
@@ -252,7 +293,8 @@
A sink that provides dummy responses in the manner of the
yaz-ztest Z39.50 server. This is useful only
- for testing.
+ for testing. Seriously, you don't need this. Pretend you didn't
+ even read this section.
@@ -262,8 +304,8 @@
A source that accepts Z39.50 and SRW connections from a port
specified in the configuration, reads protocol units, and
- feeds them into the next filter, eventually returning the
- result to the origin.
+ feeds them into the next filter in the route. When the result is
+ revceived, it is returned to the original origin.
@@ -292,8 +334,23 @@
multi
(mp::filter::Multi)
- Performs multicast searching. See the extended discussion of
- multi-database searching below.
+ Performs multicast searching.
+ See
+ the extended discussion
+ of virtual databases and multi-database searching below.
+
+
+
+
+ query_rewrite
+ (mp::filter::QueryRewrite)
+
+ 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.
@@ -303,8 +360,16 @@
When this is finished, it will implement global sharing of
result sets (i.e. between threads and therefore between
- clients), but it's not yet done.
+ 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:
+
+
+ This filter is not yet completed.
+
+
@@ -315,7 +380,8 @@
should be called nop or
passthrough?) This exists not to be used, but
to be copied - to become the skeleton of new filters as they are
- written.
+ written. As with backend_test, this is not
+ intended for civilians.
@@ -323,8 +389,14 @@
virt_db
(mp::filter::Virt_db)
- Performs virtual database selection. See the extended discussion
- of virtual databases below.
+ 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 VAL_PROXY
+ otherInfo packet. It will subsequently be used by a
+ z3950_client filter.
+ See
+ the extended discussion
+ of virtual databases and multi-database searching below.
@@ -349,7 +421,8 @@
Some other filters that do not yet exist, but which would be
useful, are briefly described. These may be added in future
- releases.
+ releases (or may be created by third parties, as loadable
+ modules).
@@ -399,6 +472,32 @@
+
+ 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
@@ -559,6 +658,15 @@
+ query_rewrite
+
+ <filter type="query_rewrite">
+ <xslt>pqf2pqf.xsl</xslt>
+ </filter>
+
+
+
+ session_shared
<filter type="session_shared">
@@ -603,30 +711,6 @@
-
- Virtual database as 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!
-
-
-
-
Module Reference