1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* This file incorporates work covered by the following license notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed
* with this work for additional information regarding copyright
* ownership. The ASF licenses this file to you under the Apache
* License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
*/
#ifndef __com_sun_star_configuration_ConfigurationAccess_idl__
#define __com_sun_star_configuration_ConfigurationAccess_idl__
#include <com/sun/star/configuration/HierarchyAccess.idl>
#include <com/sun/star/configuration/HierarchyElement.idl>
#include <com/sun/star/configuration/SetAccess.idl>
#include <com/sun/star/configuration/GroupAccess.idl>
#include <com/sun/star/configuration/AccessRootElement.idl>
#include <com/sun/star/configuration/SetElement.idl>
#include <com/sun/star/configuration/GroupElement.idl>
module com { module sun { module star { module configuration {
/** provides read access to a fragment of the configuration hierarchy.
<p>Values that are direct or indirect descendants of a root element can be
retrieved and, if themselves objects, navigated. Other interfaces provide
access to information about this element and its context.
Changes to values in the hierarchy can be monitored by event listeners.
</p>
<p>Descendants of this service also implement this service.
</p>
<p>Ultimately the configuration holds values. These values are organized into
a hierarchy using structural elements. The structure is defined in advance in
a schema. Necessary information from the schema is stored in the configuration
repository itself and is accessible through an implementation of this service.
</p>
<p>Two different kinds of structural elements are used in the configuration
hierarchy:
</p>
<dl>
<dt>Sets</dt>
<dd>are dynamic containers of homogeneous elements. Which elements
a <em>set</em> contains can vary. Their names are defined by the
clients that insert them. On the other hand, the <em>type</em> of
the elements is the same for all elements. In the case of elements
that are themselves hierarchy objects, the <em>type</em> includes
the structure of the hierarchy fragment they contain. Such types
are defined in the configuration schema as <em>templates</em>.
</dd>
<dt>Groups</dt>
<dd>are static collections of heterogeneous elements. The names and
types of the elements of a <em>group</em> are completely defined in the
configuration schema. Here each element may be of a different
<em>type</em>, allowing <em>groups</em> that contain a mix of
subobjects and simple values.
</dd>
</dl>
<p>Objects in the configuration hierarchy, for example, implementations of this service,
can thus be classified in the following ways:
</p>
<ul>
<li><em>Container</em> role:
An object that can hold child elements as a <em>set</em> or a <em>group</em>.
</li>
<li><em>Element</em> role:
An object may be an element of a <em>set</em> or a <em>group</em>
or else it may be the root element.
</li>
</ul>
<p>Several types of simple <em>values</em> can be used in the configuration.
In addition to the basic (scalar) types, sequences of the basic types are
supported. The basic types are:
</p>
<ul>
<li><strong>string</strong> can hold a human-readable text.
<p>Values are represented as <atom>string</atom>.</p>
<p>Sequences are represented as <atom dim="[]">string</atom>.</p>
<p>"<em>human-readable</em>" here excludes non-printing characters
except for CR, LF and TAB [Unicode code points 9,10,13].
For binary data, use type <strong>binary</strong> instead.</p>
</li>
<li><strong>boolean</strong> can hold the values <TRUE/> or <FALSE/>.
<p>Values are represented as <atom>boolean</atom>.
<p>Sequences are represented as <atom dim="[]">boolean</atom>.</p>
</li>
<li><strong>short</strong> can hold a 16-bit signed integer.
<p>Values are represented as <atom>short</atom>.</p>
<p>Sequences are represented as <atom dim="[]">short</atom>.</p>
</li>
<li><strong>int</strong> can hold a 32-bit signed integer.
<p>Values are represented as <atom>long</atom>.</p>
<p>Sequences are represented as <atom dim="[]">long</atom>.</p>
</li>
<li><strong>long</strong> can hold a 64-bit signed integer.
<p>Values are represented as <atom>hyper</atom>.</p>
<p>Sequences are represented as <atom dim="[]">hyper</atom>.</p>
</li>
<li><strong>double</strong> can hold a floating point number.
<p>Values are represented as <atom>double</atom>.</p>
<p>Sequences are represented as <atom dim="[]">double</atom>.</p>
</li>
<li><strong>binary</strong> can hold a sequence of octets.
<p>Values are represented as <atom dim="[]">byte</atom>.</p>
<p>Sequences are represented as <atom dim="[][]">byte</atom>.</p>
</li>
</ul>
<p>Within templates an additional type <strong>any</strong> can occur. When
such a template is used to create a new <type>SetElement</type>, the type
of the element is initially reported as <atom>any</atom> (having no value).
When the value of such an element is first set, it will assume the type used.
</p>
<p>If the schema marks a value as <em>nullable</em> (which is indicated by
attribute <const scope="com::sun::star::beans">PropertyAttribute::MAYBEVOID</const> ),
its contents may be <NULL/>.
</p>
<p>The configuration should support explicit access to default values
(implementing <type scope="com::sun::star::beans">XPropertyState</type>
and <type scope="com::sun::star::beans">XPropertyWithState</type>).
</p>
@see ConfigurationProvider
Root instances of this service can be requested from a
<type>ConfigurationProvider</type>.
@see ConfigurationUpdateAccess
an extended service that includes facilities for modifying
configuration data.
*/
published service ConfigurationAccess
{
/** provides interfaces to access child and descendent elements.
<p>An implementation actually implements a specialization of this service,
which depends on its <em>Container</em> role.
</p>
<p>Implementations shall implement exactly one of:</p>
<ul>
<li><type>SetAccess</type> if this element is a <em>Set</em>.</li>
<li><type>GroupAccess</type> if this element is a <em>Group</em>.</li>
</ul>
*/
service HierarchyAccess;
/** provides interfaces to obtain information about this element and its
role and context in the hierarchy.
<p>An implementation actually implements a specialization of this service,
which depends on its <em>Element</em> role.
</p>
<p>Implementations shall implement exactly one of:</p>
<ul>
<li><type>AccessRootElement</type> if this element is the
<em>Root</em> of the whole hierarchy. Objects that can be
created directly by a <type>ConfigurationProvider</type>
implement this service.</li>
<li><type>SetElement</type> if this element may be contained in a
<em>Set</em>.</li>
<li><type>GroupElement</type> if this element is a child of a
<em>Group</em>.</li>
</ul>
*/
service HierarchyElement;
/** specializes <type>HierarchyAccess</type>, if this element is a <em>Set</em>.
<p>This is an alternative to <type>GroupAccess</type>.
</p>
*/
[optional] service SetAccess;
/** specializes <type>HierarchyAccess</type>,
if this element is a <em>Group</em>.
<p>This is an alternative to <type>SetAccess</type>.
</p>
*/
[optional] service GroupAccess;
/** specializes <type>HierarchyElement</type>,
if this element is the <em>Root</em> of the whole hierarchy.
<p>This is an alternative to <type>SetElement</type>
or <type>GroupElement</type>.
</p>
@see ConfigurationProvider
Instances obtained from a <type>ConfigurationProvider</type> will
implement this version of <type>HierarchyElement</type>.
*/
[optional] service AccessRootElement;
/** specializes <type>HierarchyElement</type>,
if this element may be contained in a <em>Set</em>.
<p>This is an alternative to <type>AccessRootElement</type>
or <type>GroupElement</type>.
</p>
*/
[optional] service SetElement;
/** specializes <type>HierarchyElement</type>,
if this element is a child of a <em>Group</em>.
<p>This is an alternative to <type>AccessRootElement</type>
or <type>SetElement</type>.
</p>
*/
[optional] service GroupElement;
};
}; }; }; };
#endif
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
