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