configmgr/README

   1 UNO services to access the configuration database
   2
   3 == Functional Overview ==
   4
   5 This code parses the settings that are described in the [[officecfg]]
   6 directory, and provides an UNO API that code can use to set and get
   7 settings.
   8
   9 == Source Overview ==
  10
  11 configurationprovider.cxx
  12 configurationregistry.cxx
  13 defaultprovider.cxx
  14 services.cxx
  15  UNO service implementations.
  16
  17 access.cxx
  18 childaccess.cxx
  19 rootaccess.cxx
  20  UNO objects passed to clients.
  21
  22 components.cxx
  23  Central singleton that aggregates all data (reads in the XML files, manages
  24  modifications and global notifications).
  25
  26 groupnode.cxx
  27 localizedpropertynode.cxx
  28 localizedvaluenode.cxx
  29 node.cxx
  30 propertynode.cxx
  31 setnode.cxx
  32  Internal representations of data nodes.
  33
  34 parsemanager.cxx
  35 parser.hxx
  36 valueparser.cxx
  37 xcdparser.cxx
  38 xcsparser.cxx
  39 xcuparser.cxx
  40 xmldata.cxx
  41  XML file reading.
  42
  43 modifications.cxx
  44 writemodfile.cxx
  45  Modification management.
  46
  47 broadcaster.cxx
  48  Notification management.
  49
  50 additions.hxx
  51 update.cxx
  52  Extension manager interface.
  53
  54 data.cxx
  55 lock.cxx
  56 nodemap.cxx
  57 partial.cxx
  58 path.hxx
  59 type.cxx
  60  Utilities.
  61
  62
  63 == Some Implementation Notes ==
  64
  65 === Mandatory Set Members ===
  66
  67 - A set member can be marked as "mandatory," meaning that a member of that name
  68 must always be present in a set.
  69
  70 - The above definition implies that calling replaceByName on a mandatory set
  71 member is OK.
  72
  73 - The XCU format can contain oor:mandatory attributes on nodes.  (The XCS format
  74 does not support them.  In the registrymodifications file, oor:mandatory
  75 attributes should never be needed, as being mandatory cannot be controlled via
  76 the UNO API.)  The XCU reading code only evaluates the oor:mandatory attribute
  77 for set members, and ignores it everywhere else.
  78
  79 - Only true sets support mandatory members.  A localized property for the "*"
  80 locale, though acting much like a set, does not support mandatory members.
  81
  82 - The OpenOffice.org Registry Format document claims that group extension
  83 properties are implicitly mandatory, but at least the new configmgr code does
  84 not treat them like that (i.e., they can be removed again).
  85
  86 - For simplicity, setMandatory/getMandatory are available as virtual functions
  87 at the base Node, even though they can only make sense for GroupNodes and
  88 SetNodes that are set members.  The default getMandatory implementation returns
  89 NO_LAYER, meaning oor:mandatory is not set to true in any layer.  (Returning
  90 NO_LAYER simplifies the code, e.g., removeByName does not have to check whether
  91 getMandatory is called on a member of a true set to decide whether to forbid
  92 removal.)
  93
  94 - When committing changes (made through the UNO API), the "mandatory" status of
  95 inserted nodes must be updated (in case the insert is due to a replaceByName, or
  96 the "mandatory" flag was added by a concurrent modification of a lower layer).
  97 Also, for to-be-removed nodes, removal is ignored for (newly; due to concurrent
  98 modification of a lower layer) mandatory nodes (but still recorded in
  99 registrymodifications, so may take effect once the lower layer addition is
 100 removed again---whether or not that is a good idea).
 101
 102
 103 === XcuParser Modification Recording ===
 104
 105 - XcuParser records modifications when reading user layer data
 106 (valueParser_.getLayer() == Data::NO_LAYER).
 107
 108 - oor:finalized and oor:mandatory attributes cannot be set via the UNO API, so
 109 it is assumed that user layer data does not contain them (for one, they are not
 110 written by writeModFile; for another, the logic to record modifications expects
 111 a locprop(modify,fuse) to be followed by one or more value(fuse,remove), which
 112 would not necessarily be true if the locprop were only present in the user layer
 113 data to flag it as finalized).
 114
 115 - The logic to record modifications considers the top of the XML element stack.
 116 In the following list of all possible cases, items marked with an asterisk are
 117 recorded:
 118  ... group(modify,fuse) - group(modify,fuse) - ...
 119  ... group(modify,fuse) - set(modify,fuse) - ...
 120  ... group(modify,fuse) - *prop(modify,fuse,replace) - value(fuse)
 121  ... group(modify,fuse) - *prop(remove)
 122  ... group(modify,fuse) - locprop(modify,fuse) - *value(fuse)
 123  ... group(modify,fuse) - locprop(modify,fuse) - *value(remove)
 124  ... group(modify,fuse) - *locprop(replace) ...
 125  ... set(modify,fuse,replace) - group(modify/fuse) - ...
 126  ... set(modify,fuse,replace) - *group(replace/fuse) - ...
 127  ... set(modify,fuse,replace) - *group(remove)
 128  ... set(modify,fuse,replace) - set(modify/fuse) - ...
 129  ... set(modify,fuse,replace) - *set(replace/fuse) - ...
 130  ... set(modify,fuse,replace) - *set(remove)
 131 Legend: "...": zero or more further items
 132         "- ...": one or more further items
 133         "modify,fuse" etc.: any of those operations
 134         "modify/fuse": a modify or a fuse on an existing member
 135         "replace/fuse": a replace or a fuse on a non-existing member
 136