doc/filters

   1 $Id: filters,v 1.1 2006-01-17 10:43:14 mike Exp $
   2
   3
   4 YP2 Filter Classes for Superhuman Geniuses
   5 ==========================================
   6
   7 Introductory Notes
   8 ------------------
   9
  10 It's useful to think of a YP2 configuration file as a program (written
  11 in XML, but that's an implementation detail) providing a small number
  12 of primitives and operations, but operating on a very complex data
  13 type, namely the Package.  A package represents a Z39.50 or SRW/U
  14 request (whether for Init, Search, Scan, etc.) together with
  15 information about where it came from.  Packages come from front-end
  16 filters such as frontend_end, which reads them from the network; other
  17 front-end filters are possible.  They then pass along a route
  18 consisting of a sequence of filters, each of which transforms the
  19 package and may also have side-effects such as generating logging.
  20 Eventually, the route will yield a response, which is sent back to the
  21 origin.
  22
  23 There are many kinds of filter: some that are defined statically as
  24 part of YP2, and other that may be provided by third parties and
  25 dynamically loaded.  They all conform to the same simple API of
  26 essentially two methods: configure() is passed a DOM tree representing
  27 that part of the configuration file that pertains to this filter
  28 instance, and is expected to walk that tree extracting relevant
  29 information; and process() processes a Package.
  30
  31 While all filters provide the same API, there are different modes of
  32 functionality.  Some filters are sources -- they create packages
  33 (frontend_net); others are sinks -- they consume packages and return a
  34 result (z3950_client, backend_test); the others are true filters, that
  35 read process and pass on the packages they are fed (auth_simple, log,
  36 multi, session_shared, template, virt_db).
  37
  38
  39 Filters
  40 -------
  41
  42 The filters are here named by the string that is used as the "type"
  43 attribute of a <filter> element in the configuration file to request
  44 them, with the class that implements them in parentheses.
  45
  46 auth_simple (yp2::filter::AuthSimple)
  47
  48         Simple authentication and authorisation.  The configuration
  49         specifies the name of a file that is the user register, which
  50         lists username:password pairs, one per line, colon separated.
  51         When a session begins, it is rejected unless username and
  52         passsword are supplied, and match a pair in the register.
  53
  54 backend_test (yp2::filter::Backend_test)
  55
  56         A sink that provides dummy responses in the manner of the
  57         "yaz-ztest" Z39.50 server.  This is useful only for testing.
  58
  59 frontend_net (yp2::filter::FrontendNet)
  60
  61         A source that accepts Z39.50 and SRW connections from a port
  62         specified in the configuration, reads protocol units, and
  63         feeds them into the next filter, eventually returning the
  64         result to the origin.
  65
  66 log (yp2::filter::Log)
  67
  68         Writes logging information to standard output, and passes on
  69         the package unchanged.
  70
  71 multi (yp2::filter::Multi)
  72
  73         Performs multicast searching.  See the extended discussion
  74         in the file "multidb".
  75
  76 session_shared (yp2::filter::SessionShared)
  77
  78         When this is finished, it will implement global sharing of
  79         result sets (i.e. between threads and therefore between
  80         clients), but it's not yet done.
  81
  82 template (yp2::filter::Template)
  83
  84         Does nothing at all, merely passing the packet on.  (Maybe it
  85         should be called "nop" or "passthrough"?)  This exists not to
  86         be used, but to be copied -- to become the skeleton of new
  87         filters as they are written.
  88
  89 virt_db (yp2::filter::Virt_db)
  90
  91         Performs virtual database selection.  See the extended
  92         discussion in the file "multidb".
  93
  94 z3950_client (yp2::filter::Z3950Client)
  95
  96         Performs Z39.50 searching and retrieval by proxying the
  97         packages that are passed to it.  Init requests are sent to the
  98         address specified in the VAL_PROXY otherInfo attached to the
  99         request: this may have been specified by client, or generated
 100         by a virt_db filter earlier in the route.  Subsequent requests
 101         are sent to the same address, which is remembered at Init time
 102         in a Session object.
 103
 104
 105 Directions
 106 ----------
 107
 108 Some other filters that do not yet exist but would be useful:
 109 frontend_cli (source) - command-line interface for generating requests.
 110 srw2z3950 (filter) - translate SRW requests into Z39.50 requests.
 111 srw_client (sink) - performs SRW searching and retrieval.
 112 sru_client (sink) - performs SRU searching and retrieval.
 113 opensearch_client (sink) - A9 OpenSearch searching and retrieval.
 114
 115