From 9e8552ead7fb4fc4d884222c5aac08dd94e3f450 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Fri, 31 Mar 2006 16:05:27 +0000 Subject: [PATCH] Introduction, licence, architecture. --- doc/book.xml | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 149 insertions(+), 14 deletions(-) diff --git a/doc/book.xml b/doc/book.xml index 47569c2..74bd70d 100644 --- a/doc/book.xml +++ b/doc/book.xml @@ -1,23 +1,23 @@ - + Metaproxy - User's Guide and Reference MikeTaylor - - AdamDickmeiss - - - 2006 - Index Data - + + AdamDickmeiss + + + 2006 + Index Data + - Metaproxy - Generic Z39.50/SRU router/proxy. + Metaproxy - universal Z39.50/SRU router, proxy and encapsulated metasearcher - + Introduction @@ -26,15 +26,143 @@ Overview Metaproxy - is .. + is a standalone program that acts as a universal router, proxy and + encapsulated metasearcher for information retrieval protocols such + as Z39.50 and SRU/SRW. To clients, it acts as a server of these + protocols: it can be searched, records can be retrieved from it, + etc. To servers, it acts as a client: it searches in them, + 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. - ### We should probably consider saying a little more by way of - introduction. + Metaproxy is a more capable alternative to + 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 + database name, authentication and authorisation and serving local + files via HTTP. Equally significant, its modular architecture + facilitites the creation of pluggable modules implementing further + functionality. - + + + + + The Metaproxy Licence + + + No decision has yet been made on the terms under which + Metaproxy will be distributed. + + It is possible that, unlike + other Index Data products, metaproxy may not be released under a + free-software licence such as the GNU GPL. Until a decision is + 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 Metaproxy Architecture + + The Metaproxy architecture is based on three concepts: + the package, + the route + and the filter. + + + + Packages + + + A package is request or response, encoded in some protocol, + issued by a client, making its way through Metaproxy, send to or + received from a server, or sent back to the client. + + + The core of a package is the protocol unit - for example, a + Z39.50 Init Request or Search Response, or an SRU searchRetrieve + URL or Explain Response. In addition to this core, a package + also carries some extra information added and used by Metaproxy + itself. + + + In general, packages are doctored as they pass through + Metaproxy. For example, when the proxy performs authentication + and authorisation on a Z39.50 Init request, it removes the + authentication credentials from the package so that they are not + passed onto the back-end server; and when search-response + packages are obtained from multiple servers, they are merged + into a single unified package that makes its way back to the + client. + + + + + Routes + + + Packages make their way through routes, which can be thought of + as programs that operate on the package data-type. Each + incoming package initially makes its way through a default + route, but may be switched to a different route based on various + considerations. Routes are made up of sequences of filters (see + below). + + + + + Filters + + + Filters provide the individual instructions within a route, and + effect the necessary transformations on packages. A particular + configuration of Metaproxy is essentially a set of filters, + described by configuration details and arranged in order in one + or more routes. There are many kinds of filter - about a dozen + at the time of writing with more appearing all the time - each + performing a specific function and configured by different + information. + + + The word ``filter'' is sometimes used rather loosely, in two + 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 + operational terms, of these is a separate filter. In practice, + context always make it clear which sense of the word ``filter'' + is being used. + + + Extensibility of Metaproxy is primarily through the creation of + plugins that provide new filters. The filter API is small and + conceptually simple, but there are many details to master. See + the section below on + extensions. + + + + + + Since packages are created and handled by the system itself, and + routes are conceptually simple, most of the remainder of this + document concentrates on filters. After a brief overview of the + filter types follows, along with some thoughts on possible future + directions. + + + @@ -84,6 +212,7 @@ (auth_simple, log, multi, + query_rewrite, session_shared, template, virt_db). @@ -506,6 +635,11 @@ &manref; + + Writing extensions for Metaproxy + ### + + Classes in the Metaproxy source code @@ -783,5 +917,6 @@ sgml-parent-document: "main.xml" sgml-local-catalogs: nil sgml-namecase-general:t + nxml-child-indent: 1 End: --> -- 1.7.10.4