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 156