xref: /trunk/main/configmgr/source/README (revision e76eebc6)
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