stoc/README.md

   1 # Registries, Reflection, Introspection Implementation for UNO
   2
   3 The UNO types and services bootstrapping code is very old, and concepts
   4 are tightly knit together. Whenever you want to change something you risk
   5 backwards incompatibility.  The code causes mental pain, and whenever
   6 you need to touch it you want to run away screaming.  One typically ends
   7 up doing minimally invasive changes.  That way, you have a chance of
   8 surviving the process.  But you also pile up guilt.
   9
  10 At the heart of the matter there is the old binary "store" file structure
  11 and the `XRegistry` interface on top of it.  At runtime, both all the UNO
  12 type information (scattered across a number of binary `.rdb` files) and
  13 all the UNO service information (scattered across a number of `.rdb` files
  14 that used to be binary but have been mostly changed to XML now) are
  15 represented by a single `XRegistry` instance each.
  16
  17 The way the respective information is represented in the `XRegistry`
  18 interface simply corresponds to the way the information is stored in the
  19 binary `.rdb` files.  Those files are designed for storage of hierarchically
  20 nested small blobs of information.  Hence, for example information about
  21 a UNO interface type `com.sun.star.foo.XBar` is stored in a nested "folder"
  22 with path `com - sun - star - foo - XBar`, containing little blobs of
  23 information about the type's ancestors, its methods, etc.  Similarly
  24 for information about instantiable services like `com.sun.star.baz.Boz`.
  25
  26 As there are typically multiple `.rdb` files containing types resp.
  27 services (URE specific, LO specific, from extensions, ...), but they need
  28 to be represented by a single `XRegistry` instance, so "nested registries"
  29 were invented.  They effectively form a linear list of chaining `XRegistry`
  30 instances together.  Whenever a path needs to be looked up in the top-level
  31 registry, it effectively searches through the linear list of nested
  32 registries.  All with the cumbersome UNO `XRegistry` interface between
  33 the individual parts.  Horror.
  34
  35 When the XML service `.rdb`s were introduced, we chickened out (see above
  36 for rationale) and put them behind an `XRegistry` facade, so that they
  37 would seamlessly integrate with the existing mess. We postponed
  38 systematic clean-up to the pie-in-the-sky days of LibreOffice 4 (or, "once we'll
  39 become incompatible with OpenOffice.org," as the phrase used to be back then)