From 159aa22e4ae8842da0f6d03ed5a840af3ee213c4 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Tue, 17 Jan 2006 10:43:14 +0000 Subject: [PATCH] New --- doc/filters | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 doc/filters diff --git a/doc/filters b/doc/filters new file mode 100644 index 0000000..c4ce443 --- /dev/null +++ b/doc/filters @@ -0,0 +1,115 @@ +$Id: filters,v 1.1 2006-01-17 10:43:14 mike Exp $ + + +YP2 Filter Classes for Superhuman Geniuses +========================================== + +Introductory Notes +------------------ + +It's useful to think of a YP2 configuration file as a program (written +in XML, but that's an implementation detail) providing a small number +of primitives and operations, but operating on a very complex data +type, namely the Package. A package represents a Z39.50 or SRW/U +request (whether for Init, Search, Scan, etc.) together with +information about where it came from. Packages come from front-end +filters such as frontend_end, 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. + +There are many kinds of filter: some that are defined statically as +part of YP2, and other that may be provided by third parties and +dynamically loaded. They all conform to the same simple API of +essentially two methods: configure() is passed a DOM tree representing +that part of the configuration file that pertains to this filter +instance, and is expected to walk that tree extracting relevant +information; and process() processes a Package. + +While all filters provide the same API, there are different modes of +functionality. Some filters are sources -- they create packages +(frontend_net); others are sinks -- they consume packages and return a +result (z3950_client, backend_test); the others are true filters, that +read process and pass on the packages they are fed (auth_simple, log, +multi, session_shared, template, virt_db). + + +Filters +------- + +The filters are here named by the string that is used as the "type" +attribute of a element in the configuration file to request +them, with the class that implements them in parentheses. + +auth_simple (yp2::filter::AuthSimple) + + Simple authentication and authorisation. The configuration + specifies the name of a file that is the user register, which + 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. + +backend_test (yp2::filter::Backend_test) + + A sink that provides dummy responses in the manner of the + "yaz-ztest" Z39.50 server. This is useful only for testing. + +frontend_net (yp2::filter::FrontendNet) + + 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. + +log (yp2::filter::Log) + + Writes logging information to standard output, and passes on + the package unchanged. + +multi (yp2::filter::Multi) + + Performs multicast searching. See the extended discussion + in the file "multidb". + +session_shared (yp2::filter::SessionShared) + + 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. + +template (yp2::filter::Template) + + Does nothing at all, merely passing the packet on. (Maybe it + 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. + +virt_db (yp2::filter::Virt_db) + + Performs virtual database selection. See the extended + discussion in the file "multidb". + +z3950_client (yp2::filter::Z3950Client) + + 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 VAL_PROXY otherInfo attached to the + request: this may have been specified by client, or generated + by a virt_db filter earlier in the route. Subsequent requests + are sent to the same address, which is remembered at Init time + in a Session object. + + +Directions +---------- + +Some other filters that do not yet exist but would be useful: +frontend_cli (source) - command-line interface for generating requests. +srw2z3950 (filter) - translate SRW requests into Z39.50 requests. +srw_client (sink) - performs SRW searching and retrieval. +sru_client (sink) - performs SRU searching and retrieval. +opensearch_client (sink) - A9 OpenSearch searching and retrieval. + + -- 1.7.10.4