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