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
236
237
238
|
/* -*- 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_ConfigurationProvider_idl__
#define __com_sun_star_configuration_ConfigurationProvider_idl__
#include <com/sun/star/lang/XMultiServiceFactory.idl>
#include <com/sun/star/lang/XComponent.idl>
module com { module sun { module star { module configuration {
/** manages one, or more, complete sets of configuration data and serves as a
factory for objects that provide access to a subset of the configuration.
<p>An implementation is usually obtained from a
<type scope="com::sun::star::lang">ServiceManager</type>. The arguments passed to
<member scope="com::sun::star::lang">XMultiComponentFactory::createInstanceWithContextAndArguments()</member>
select the configuration data source. Arguments must be provided as
<type scope="com::sun::star::beans">NamedValue</type>
or <type scope="com::sun::star::beans">PropertyValue</type>.
If the parameters given are incomplete missing values are taken
from the context or the environment. If an instance already exists for the
given set of arguments, the existing instance may be reused.
In particular, instantiating a provider without explicit arguments to access
the default configuration data will always yield the same
<type scope="com::sun::star::configuration">DefaultProvider</type> object.
</p>
<p>Some arguments for
<member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
may be given default values during creation of this service. In particular
this applies to the parameters <code>"Locale"</code> and <code>"EnableAsync"</code>.
</p>
@deprecated Use <type>theDefaultProvider</type> instead.
*/
published service ConfigurationProvider
{
/** allows creating access objects for specific views such as subsets and fragments
of the configuration.
<p>The parameter <var>aServiceSpecifier</var> passed to
<member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
supports at least the service specifiers
<code>"com.sun.star.configuration.ConfigurationAccess"</code> and
<code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>.
</p>
<p>Using the first of these service specifiers requests a read-only view of
the configuration.
The object that is created implements service <type>ConfigurationAccess</type>.
To reflect its <em>element role</em> as root of the view, it implements
service <type>AccessRootElement</type>.
</p>
<p>Using the second form requests an updatable view of the configuration.
The object that is created should implement service
<type>ConfigurationUpdateAccess</type>. To reflect its <em>element role</em>
which includes controlling updates for the whole view, it implements
service <type>UpdateRootElement</type>.
<BR />If the root element of the view is marked read-only (as indicated
by <const scope="com::sun::star::beans">PropertyAttributes::READONLY</const>),
the implementation may either raise an exception or return a (read-only)
<type>ConfigurationAccess</type>/<type>AccessRootElement</type> instead.
</p>
<p>The arguments passed to
<member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
in parameter <var>aArguments</var> specify the view of the configuration that
should be created. That is, they determine the subset of elements that can be
accessed starting from the returned object. Each element of the argument
sequence should be a <type scope="com::sun::star::beans">PropertyValue</type>
or a <type scope="com::sun::star::beans">NamedValue</type>,
so that the parameters can be identified by name rather than by position.
</p>
<p>What combinations of arguments are supported depends on the service name.
</p>
<p>With both of the standard service-specifiers above, an implementation must
accept a single argument named <code>nodepath</code> of type <atom>string</atom>.
This argument must contain the absolute path to an element of the
configuration. The view that is selected consists of the named element and
all its descendants.
</p>
<p>Other arguments can be used to control the behavior of the view. These
are different for different implementations. Whether and how they are used
may also depend on the configuration store and configuration that were
selected when the provider was created.
</p>
<p>An implementation must ignore unknown arguments.</p>
<p>Some parameters that are commonly supported are:</p>
<ul>
<li>
<strong>Selecting data into a view:</strong>
<dl>
<dt><code>"nodepath"</code> : <atom>string</atom></dt>
<dd>specifies the location of the view root in the configuration.</dd>
<dt><code>"depth"</code> : <atom>short</atom></dt>
<dd>specifies that elements of the hierarchy that are more than the given
number of nesting levels away from the root need not be included in the
view.
</dd>
<dt><code>"locale"</code> : <type scope="com::sun::star::lang">Locale</type></dt>
<dd>specifies the locale for which localized values should be
retrieved.
</dd>
</dl>
<p><strong>Example:</strong> In the hierarchy
<BR /><pre>
A - B1 - C1
|
- B2 - C2 (localized: de, en, fr, ..)
| |
| - C3 - D1
| | |
| | - D2 - E1
| |
| - C4 - D3 - E2 - F1
| | |
| | - F2
| |
| - C5
|
- B3
|
- B4 - C6 - D4 - E3
</pre>
<BR />selecting a view with <code>nodepath = "/A/B2"</code>,
<code>depth = 2</code> and <code>locale = <Locale for en_US></code>
would result in the tree fragment
<BR /><pre>
(A-) B2 - C2 (en)
|
- C3 - D1
| |
| - D2 (..)
|
- C4 - D3 (..)
|
- C5
</pre>
</p>
</li>
<li>
<strong>Controlling cache behavior:</strong> (with providers that
cache configuration data)
<dl>
<dt><code>"enableasync"</code> : <atom>boolean</atom></dt>
<dd>controls how updates are handled in the cache. If <TRUE/>, the
cache may operate in <em>write-back</em> mode, where updates at
first only affect the cache and are written to persistent storage
at some later time. If <FALSE/>, the cache must operate in
<em>write-through</em> mode, where updates are written to persistent
storage at once - that is before
<member scope="com::sun::star::util">XChangesBatch::commitChanges()</member>
returns.
<p><em>This parameter was formerly called <code>"lazywrite"</code>.
The old name should still be supported for compatibility.
</em></p>
</dd>
<dt><code>"nocache"</code> : <atom>boolean</atom></dt>
<dd>This deprecated parameter
specifies that data for the view is not taken from the cache, but
read directly from storage. This may entail that future changes that
become visible in the cache are not reflected in this view and that
changes done through this view are not reflected in the cache.
<BR /><strong>Use with caution !</strong>
<p><em>This parameter is not supported by all implementations and may be
silently ignored !
</em></p>
</dd>
</dl>
</li>
</ul>
<p><member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member>
may be unusable. Only an implementation that supports service names that can be
used with no further arguments support this method. It should return the
same result as if
<member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
had been called using an empty sequence of arguments.
</p>
*/
interface com::sun::star::lang::XMultiServiceFactory;
/** allows controlling or observing the lifetime of the configuration.
<p>The owner of the provider may dispose of this object
using <member scope="com::sun::star::lang">XComponent::dispose()</member>.
Note that the default provider is owned by the
<type scope="com::sun::star::lang">ServiceManager</type> and should not be
disposed of by user code.
</p>
<p>Views created by the provider generally refer to data that is managed by
the provider. Therefore, disposing of the provider will cause all objects
belonging to these views to be disposed of as well. This does not apply to
<em>snapshot</em> views that have their own copy of the data, if available.
</p>
*/
interface com::sun::star::lang::XComponent;
};
}; }; }; };
#endif
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
