New

diff --git a/doc/filters b/doc/filters
new file mode 100644 (file)
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 <filter> 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.
+
+