doc/to-be-integrated

   1 I am a bit torn on that subject.  The current filter API really is
   2 super-simple: it consist of almost exactly one entry-point, called
   3 process(), which is called with a package as its argument, and which
   4 has to Do Some Stuff.  That's all.  It doesn't even return a value,
   5 it's literally
   6         void process(Package & package);
   7
   8 Except, of course, that simplicity is very misleading.  It's simple in
   9 the way that a word-process program is simple if it consists only of
  10 the main function:
  11
  12         int main() {
  13             do_word_processing();
  14             return 0;
  15         }
  16
  17 The phrase "Do Some Stuff" conceals a whole world of hurt, in which
  18 the filters need to pick apart the Package objects and the PDUs that
  19 they contain, and do all sorts of clever things with state, and call
  20 downstram filters, and set members of the Package structure to
  21 indicate whether the processing was successful, and so on.
  22
  23 On the plus side, this approach is _conceptually_ very simple, and
  24 immensely powerful since there is pretty much no limit to what
  25 process() might do.  Also, it means there's not too much work for
  26 Doxygen to do :-)  On the negative side, it makes it pretty hard to
  27 get into writing filters unless you're familiar with the Package class
  28 and all the APDU structures, and the utility methods and classes that
  29 Adam has added in on what I think is a fairly ad-hoc basis.
  30
  31 This is in very stark contrast to the YAZ Classic frontend server API,
  32 with its bend_init() and suchlike.  That API makes simple things easy
  33 to do, but is restrictive when you want to do exotic things; whereas
  34 with the Metaproxy API, _nothing_ is easy but _everything_ is
  35 possible.  (Adam, do shout if you think I am mischaracterising
  36 anything here -- all of this is just my own impression.)
  37
  38 So I don't think it's possible to add what you described as "an extra
  39 layer of general-ness" -- it's already as general as it can be.  But
  40 it _would_ be possible to add an "extra layer of specific-ness", and
  41 that might (might) be useful.  The obvious way to do it is as a filter
  42 that provides glue to the classic frontend server API: it would look
  43 at the APDUs in the packages it's passed, make the corresponding
  44 bend_*() calls, interpret the results and stick the relevant bits of
  45 status information back into the package.  This would actually be
  46 rather cute: as well as making it much easier to write new back-ends,
  47 it would provide a zero-pain way of integrating existing backend
  48 applications -- not least Zebra -- into Metaproxy.  It would also mean
  49 that, for every new filter that someone sets out to write, they could
  50 choose between doing it with the Filter or Backend API.