$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.