1 $Id: filters,v 1.1 2006-01-17 10:43:14 mike Exp $
4 YP2 Filter Classes for Superhuman Geniuses
5 ==========================================
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
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.
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).
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.
46 auth_simple (yp2::filter::AuthSimple)
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.
54 backend_test (yp2::filter::Backend_test)
56 A sink that provides dummy responses in the manner of the
57 "yaz-ztest" Z39.50 server. This is useful only for testing.
59 frontend_net (yp2::filter::FrontendNet)
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
66 log (yp2::filter::Log)
68 Writes logging information to standard output, and passes on
69 the package unchanged.
71 multi (yp2::filter::Multi)
73 Performs multicast searching. See the extended discussion
74 in the file "multidb".
76 session_shared (yp2::filter::SessionShared)
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.
82 template (yp2::filter::Template)
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.
89 virt_db (yp2::filter::Virt_db)
91 Performs virtual database selection. See the extended
92 discussion in the file "multidb".
94 z3950_client (yp2::filter::Z3950Client)
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
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.