configmgr/README.md

   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 a 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 LibreOffice 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
 119         ... group(modify,fuse) - group(modify,fuse) - ...
 120         ... group(modify,fuse) - set(modify,fuse) - ...
 121         ... group(modify,fuse) - *prop(modify,fuse,replace) - value(fuse)
 122         ... group(modify,fuse) - *prop(remove)
 123         ... group(modify,fuse) - locprop(modify,fuse) - *value(fuse)
 124         ... group(modify,fuse) - locprop(modify,fuse) - *value(remove)
 125         ... group(modify,fuse) - *locprop(replace) ...
 126         ... set(modify,fuse,replace) - group(modify/fuse) - ...
 127         ... set(modify,fuse,replace) - *group(replace/fuse) - ...
 128         ... set(modify,fuse,replace) - *group(remove)
 129         ... set(modify,fuse,replace) - set(modify/fuse) - ...
 130         ... set(modify,fuse,replace) - *set(replace/fuse) - ...
 131         ... set(modify,fuse,replace) - *set(remove)
 132         Legend:
 133             "...": zero or more further items
 134             "- ...": one or more further items
 135             "modify,fuse" etc.: any of those operations
 136             "modify/fuse": a modify or a fuse on an existing member
 137             "replace/fuse": a replace or a fuse on a non-existing member