configmgr/source/README

   1 #*************************************************************************
   2 #
   3 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4 #
   5 # Copyright 2000, 2010 Oracle and/or its affiliates.
   6 #
   7 # OpenOffice.org - a multi-platform office productivity suite
   8 #
   9 # This file is part of OpenOffice.org.
  10 #
  11 # OpenOffice.org is free software: you can redistribute it and/or modify
  12 # it under the terms of the GNU Lesser General Public License version 3
  13 # only, as published by the Free Software Foundation.
  14 #
  15 # OpenOffice.org is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 # GNU Lesser General Public License version 3 for more details
  19 # (a copy is included in the LICENSE file that accompanied this code).
  20 #
  21 # You should have received a copy of the GNU Lesser General Public License
  22 # version 3 along with OpenOffice.org.  If not, see
  23 # <http://www.openoffice.org/license.html>
  24 # for a copy of the LGPLv3 License.
  25 #
  26 #***********************************************************************/
  27
  28 Source Overview
  29 ===============
  30
  31 configurationprovider.cxx
  32 configurationregistry.cxx
  33 defaultprovider.cxx
  34 services.cxx
  35  UNO service implementations.
  36
  37 access.cxx
  38 childaccess.cxx
  39 rootaccess.cxx
  40  UNO objects passed to clients.
  41
  42 components.cxx
  43  Central singleton that aggregates all data (reads in the XML files, manages
  44  modifications and global notifications).
  45
  46 groupnode.cxx
  47 localizedpropertynode.cxx
  48 localizedvaluenode.cxx
  49 node.cxx
  50 propertynode.cxx
  51 setnode.cxx
  52  Internal representations of data nodes.
  53
  54 parsemanager.cxx
  55 parser.hxx
  56 valueparser.cxx
  57 xcdparser.cxx
  58 xcsparser.cxx
  59 xcuparser.cxx
  60 xmldata.cxx
  61  XML file reading.
  62
  63 modifications.cxx
  64 writemodfile.cxx
  65  Modification management.
  66
  67 broadcaster.cxx
  68  Notification management.
  69
  70 additions.hxx
  71 update.cxx
  72  Extension manager interface.
  73
  74 data.cxx
  75 lock.cxx
  76 nodemap.cxx
  77 partial.cxx
  78 path.hxx
  79 type.cxx
  80  Utilities.
  81
  82
  83 Mandatory Set Members
  84 =====================
  85
  86 - A set member can be marked as "mandatory," meaning that a member of that name
  87 must always be present in a set.
  88
  89 - The above definition implies that calling replaceByName on a mandatory set
  90 member is OK.
  91
  92 - The XCU format can contain oor:mandatory attributes on nodes.  (The XCS format
  93 does not support them.  In the registrymodifications file, oor:mandatory
  94 attributes should never be needed, as being mandatory cannot be controlled via
  95 the UNO API.)  The XCU reading code only evaluates the oor:mandatory attribute
  96 for set members, and ignores it everywhere else.
  97
  98 - Only true sets support mandatory members.  A localized property for the "*"
  99 locale, though acting much like a set, does not support mandatory members.
 100
 101 - The OpenOffice.org Registry Format document claims that group extension
 102 properties are implicitly mandatory, but at least the new configmgr code does
 103 not treat them like that (i.e., they can be removed again).
 104
 105 - For simplicity, setMandatory/getMandatory are available as virtual functions
 106 at the base Node, even though they can only make sense for GroupNodes and
 107 SetNodes that are set members.  The default getMandatory implementation returns
 108 NO_LAYER, meaning oor:mandatory is not set to true in any layer.  (Returning
 109 NO_LAYER simplifies the code, e.g., removeByName does not have to check whether
 110 getMandatory is called on a member of a true set to decide whether to forbid
 111 removal.)
 112
 113 - When committing changes (made through the UNO API), the "mandatory" status of
 114 inserted nodes must be updated (in case the insert is due to a replaceByName, or
 115 the "mandatory" flag was added by a concurrent modification of a lower layer).
 116 Also, for to-be-removed nodes, removal is ignored for (newly; due to concurrent
 117 modification of a lower layer) mandatory nodes (but still recorded in
 118 registrymodifications, so may take effect once the lower layer addition is
 119 removed again---whether or not that is a good idea).
 120
 121
 122 XcuParser Modification Recording
 123 ================================
 124
 125 - XcuParser records modifications when reading user layer data
 126 (valueParser_.getLayer() == Data::NO_LAYER).
 127
 128 - oor:finalized and oor:mandatory attributes cannot be set via the UNO API, so
 129 it is assumed that user layer data does not contain them (for one, they are not
 130 written by writeModFile; for another, the logic to record modifications expects
 131 a locprop(modify,fuse) to be followed by one or more value(fuse,remove), which
 132 would not necessarily be true if the locprop were only present in the user layer
 133 data to flag it as finalized).
 134
 135 - The logic to record modifications considers the top of the XML element stack.
 136 In the following list of all possible cases, items marked with an asterisk are
 137 recorded:
 138  ... group(modify,fuse) - group(modify,fuse) - ...
 139  ... group(modify,fuse) - set(modify,fuse) - ...
 140  ... group(modify,fuse) - *prop(modify,fuse,replace) - value(fuse)
 141  ... group(modify,fuse) - *prop(remove)
 142  ... group(modify,fuse) - locprop(modify,fuse) - *value(fuse)
 143  ... group(modify,fuse) - locprop(modify,fuse) - *value(remove)
 144  ... group(modify,fuse) - *locprop(replace) ...
 145  ... set(modify,fuse,replace) - group(modify/fuse) - ...
 146  ... set(modify,fuse,replace) - *group(replace/fuse) - ...
 147  ... set(modify,fuse,replace) - *group(remove)
 148  ... set(modify,fuse,replace) - set(modify/fuse) - ...
 149  ... set(modify,fuse,replace) - *set(replace/fuse) - ...
 150  ... set(modify,fuse,replace) - *set(remove)
 151 Legend: "...": zero or more further items
 152         "- ...": one or more further items
 153         "modify,fuse" etc.: any of those operations
 154         "modify/fuse": a modify or a fuse on an existing member
 155         "replace/fuse": a replace or a fuse on a non-existing member