doc/classes

   1 $Id: classes,v 1.3 2006-01-16 15:22:56 mike Exp $
   2
   3
   4 A Hitch-Hiker's Guide to the YP2 Classes
   5 ========================================
   6
   7 Introductory Notes
   8 ------------------
   9
  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).
  14
  15
  16 Classes
  17 =======
  18
  19 yp::FactoryFilter
  20 -----------------
  21
  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
  27 loaded dynamically.
  28
  29 yp2::FactoryStatic
  30 ------------------
  31
  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.
  38
  39 yp2::filter::Base
  40 -----------------
  41
  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
  49 anything useful.
  50
  51 yp2::filter::AuthSimple, Backend_test, FrontendNet, etc.
  52 --------------------------------------------------------
  53
  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).
  61
  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.
  67
  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: ### no idea -- not used in sample configs
  76 - template: ### no idea -- not used in sample configs
  77 - virt_db: chooses which server/db to use based on database name
  78 - z3950_client: forwards PDUs to a nominated Z39.50 server
  79
  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?
  82
  83 yp2::Package
  84 ------------
  85
  86 ###
  87
  88 yp2::Pipe
  89 ---------
  90
  91 ###
  92
  93
  94 yp2::Router and yp2::RouterChain
  95 --------------------------------
  96
  97 ###
  98
  99
 100 yp2::RouterFleXML
 101 -----------------
 102
 103 ###
 104
 105
 106 yp2::Session
 107 ------------
 108
 109 ###
 110
 111 yp2::ThreadPoolSocketObserver
 112 -----------------------------
 113
 114 ###
 115
 116 yp2::util
 117 ---------
 118
 119 A namespace of various small utility functions and classes, collected
 120 together for convenience.  Most importantly, includes the
 121 yp2::util::odr class, a wrapper for YAZ's ODR facilities.
 122
 123
 124 yp2::xml
 125 ---------
 126
 127 A namespace of various XML utility functions and classes, collected
 128 together for convenience.
 129
 130
 131 Other Source Files
 132 ==================
 133
 134 ex_router_flexml.cpp -- the main function of the proxy.
 135 yp2_prog.cpp -- identical to the above: it's not clear why.
 136 test_*.cpp -- unit-tests for various modules.