1 $Id: classes,v 1.4 2006-01-17 09:26:44 mike Exp $
4 A Hitch-Hiker's Guide to the YP2 Classes
5 ========================================
10 In general, classes seem to be named big-endianly, so that
11 "FactoryFilter" is not a filter for factories, but a factory that
12 produces filters, and "FactoryStatic" is a factory for the statically
13 registered filters (as opposed to those that are dynamically loaded).
22 A factory class that exists primarily to provide the create() method,
23 which takes the name of a filter class as its argument and returns a
24 new filter of that type. To enable this, the factory must first be
25 populated by calling add_creator() for static filters (this is done by
26 the FactoryStatic class, see below) and add_creator_dyn() for filters
32 A subclass of FactoryFilter which is responsible for registering all
33 the statically defined filter types. It does this by knowing about
34 all those filters' structures, which are listed in its constructor.
35 Merely instantiating this class registers all the static classes. It
36 is for the benefit of this class that struct yp2_filter_struct exists,
37 and that all the filter classes provide a static object of that type.
42 The virtual base class of all filters. The filter API is, on the
43 surface at least, extremely simple: two methods. configure() is
44 passed a DOM tree representing that part of the configuration file
45 that pertains to this filter instance, and is expected to walk that
46 tree extracting relevant information. And process() processes a
47 Package (see below). That surface simplicitly is a bit misleading, as
48 process() needs to know a lot about the Package class in order to do
51 yp2::filter::AuthSimple, Backend_test, FrontendNet, etc.
52 --------------------------------------------------------
54 Individual filters. Each of these is implemented by a header and a
55 source file, named filter_*.hpp and filter_*.cpp respectively. All
56 the header files should be pretty much identical, in that they declare
57 the class, including a private Rep class and a member pointer to it,
58 and the two public methods. The only extra information in any filter
59 header is additional private types and members (the latter should
60 really all be in the Rep anyway).
62 The source file for each filter needs to supply:
63 - a definition of the private Rep class
64 - some boilerplate constructors and destructors
65 - a configure() method that uses the appropriate XML fragment
66 - most important, the prcoess() method that does all the actual work.
68 In a better world, each of the filters (nine so far) would be
69 documented separately. Very, very briefly, though:
70 - auth_simple: authentication against a plain-text file
71 - backend_test: trivial ztest-like dummy hardwired back-end
72 - frontend_net: receives incoming Z39.50 and SRW PSUs
73 - log: writes log messages
74 - multi: fans out searches to multiple back-ends
75 - session_shared: global sharing of cached result-sets
76 - template: NOT TO BE USED: just a template source file for new filters
77 - virt_db: chooses which server/db to use based on database name
78 - z3950_client: forwards PDUs to a nominated Z39.50 server
80 ### What is "filter_dl.cpp"? It's to do with dynamic loading, but in
81 what way and to what extent does it function as a filter?
83 See the file "filters" for more information.
89 Represents a package on its way through the series of filters that
90 make up a route. This is essentially a Z39.50 or SRU APDU together
91 with information about where it came from, which is modified as it
92 passes through the various filters.
98 This class provides a compatibility layer so that we have an IPC
99 mechanism that works the same under Unix and Windows. It's not
100 particularly exciting.
103 yp2::Router and yp2::RouterChain
104 --------------------------------
120 yp2::ThreadPoolSocketObserver
121 -----------------------------
128 A namespace of various small utility functions and classes, collected
129 together for convenience. Most importantly, includes the
130 yp2::util::odr class, a wrapper for YAZ's ODR facilities.
136 A namespace of various XML utility functions and classes, collected
137 together for convenience.
143 ex_router_flexml.cpp -- the main function of the proxy.
144 yp2_prog.cpp -- identical to the above: it's not clear why.
145 test_*.cpp -- unit-tests for various modules.