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
22
23#ifndef __com_sun_star_configuration_ConfigurationProvider_idl__
24#define __com_sun_star_configuration_ConfigurationProvider_idl__
25
26#ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
27#include <com/sun/star/lang/XMultiServiceFactory.idl>
28#endif
29
30#ifndef __com_sun_star_lang_XComponent_idl__
31#include <com/sun/star/lang/XComponent.idl>
32#endif
33
34//=============================================================================
35
36module com { module sun { module star { module configuration {
37
38//=============================================================================
39/** manages one, or more, complete sets of configuration data and serves as a
40 factory for objects that provide access to a subset of the configuration.
41
42 <p>An implementation is usually obtained from a
43 <type scope="com::sun::star::lang">ServiceManager</type>. The arguments passed to
44 <member scope="com::sun::star::lang">XMultiComponentFactory::createInstanceWithContextAndArguments()</member>
45 select the configuration data source. Arguments must be provided as
46 <type scope="com::sun::star::beans">NamedValue</type>
47 or <type scope="com::sun::star::beans">PropertyValue</type>.
48 If the parameters given are incomplete missing values are taken
49 from the context or the environment. If an instance already exists for the
50 given set of arguments, the existing instance may be reused.
51 In particular, instantiating a provider without explicit arguments to access
52 the default configuration data will always yield the same
53 <type scope="com::sun::star::configuration">DefaultProvider</type> object.
54 </p>
55 <p>Some arguments for
56 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
57 may be given default values during creation of this service. In particular
58 this applies to the parameters <code>"Locale"</code> and <code>"EnableAsync"</code>.
59 </p>
60 */
61published service ConfigurationProvider
62{
63/** allows creating access objects for specific views such as subsets and fragments
64 of the configuration.
65
66 <p>The parameter <var>aServiceSpecifier</var> passed to
67 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
68 supports at least the service specifiers
69 <code>"com.sun.star.configuration.ConfigurationAccess"</code> and
70 <code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>.
71 </p>
72
73 <p>Using the first of these service specifiers requests a read-only view of
74 the configuration.
75 The object that is created implements service <type>ConfigurationAccess</type>.
76 To reflect its <em>element role</em> as root of the view, it implements
77 service <type>AccessRootElement</type>.
78 </p>
79
80 <p>Using the second form requests an updatable view of the configuration.
81 The object that is created should implement service
82 <type>ConfigurationUpdateAccess</type>. To reflect its <em>element role</em>
83 which includes controlling updates for the whole view, it implements
84 service <type>UpdateRootElement</type>.
85 <BR />If the root element of the view is marked read-only (as indicated
86 by <const scope="com::sun::star::beans">PropertyAttributes::READONLY</const>),
87 the implementation may either raise an exception or return a (read-only)
88 <type>ConfigurationAccess</type>/<type>AccessRootElement</type> instead.
89 </p>
90
91 <p>The arguments passed to
92 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
93 in parameter <var>aArguments</var> specify the view of the configuration that
94 should be created. That is, they determine the subset of elements that can be
95 accessed starting from the returned object. Each element of the argument
96 sequence should be a <type scope="com::sun::star::beans">PropertyValue</type>
97 or a <type scope="com::sun::star::beans">NamedValue</type>,
98 so that the parameters can be identified by name rather than by position.
99 </p>
100
101 <p>What combinations of arguments are supported depends on the service name.
102 </p>
103
104 <p>With both of the standard service-specifiers above, an implementation must
105 accept a single argument named <code>nodepath</code> of type <atom>string</atom>.
106 This argument must contain the absolute path to an element of the
107 configuration. The view that is selected consists of the named element and
108 all its descendants.
109 </p>
110
111 <p>Other arguments can be used to control the behavior of the view. These
112 are different for different implementations. Whether and how they are used
113 may also depend on the configuration store and configuration that were
114 selected when the provider was created.
115 </p>
116
117 <p>An implementation must ignore unknown arguments.</p>
118
119 <p>Some parameters that are commonly supported are:</p>
120
121 <ul>
122    <li>
123       <strong>Selecting data into a view:</strong>
124       <dl>
125	     <dt><code>"nodepath"</code> : <atom>string</atom></dt>
126	     <dd>specifies the location of the view root in the configuration.</dd>
127	     <dt><code>"depth"</code> : <atom>short</atom></dt>
128	     <dd>specifies that elements of the hierarchy that are more than the given
129	      number of nesting levels away from the root need not be included in the
130	      view.
131	     </dd>
132	     <dt><code>"locale"</code> : <type scope="com::sun::star::lang">Locale</type></dt>
133	     <dd>specifies the locale for which localized values should be
134		  retrieved.
135		 </dd>
136       </dl>
137
138	   <p><strong>Example:</strong> In the hierarchy
139<BR /><pre>
140 A - B1 - C1
141   |
142   - B2 - C2 (localized: de, en, fr, ..)
143   |    |
144   |    - C3 - D1
145   |    |    |
146   |    |    - D2 - E1
147   |    |
148   |    - C4 - D3 - E2 - F1
149   |    |              |
150   |    |              - F2
151   |    |
152   |    - C5
153   |
154   - B3
155   |
156   - B4 - C6 - D4 - E3
157
158</pre>
159         <BR />selecting a view with <code>nodepath = "/A/B2"</code>,
160		 <code>depth = 2</code> and <code>locale = &lt;Locale for en_US&gt;</code>
161		 would result in the tree fragment
162<BR /><pre>
163(A-) B2 - C2 (en)
164        |
165        - C3 - D1
166        |    |
167        |    - D2 (..)
168        |
169        - C4 - D3 (..)
170        |
171        - C5
172
173</pre>
174	   </p>
175    </li>
176
177    <li>
178       <strong>Controlling cache behavior:</strong> (with providers that
179	    cache configuration data)
180       <dl>
181	     <dt><code>"enableasync"</code> : <atom>boolean</atom></dt>
182	     <dd>controls how updates are handled in the cache. If <TRUE/>, the
183		  cache may operate in <em>write-back</em> mode, where updates at
184		  first only affect the cache and are written to persistent storage
185		  at some later time. If <FALSE/>, the cache must operate in
186		  <em>write-through</em> mode, where updates are written to persistent
187		  storage at once - that is before
188		  <member scope="com::sun::star::util">XChangesBatch::commitChanges()</member>
189		  returns.
190          <p><em>This parameter was formerly called <code>"lazywrite"</code>.
191            The old name should still be supported for compatibility.
192          </em></p>
193		 </dd>
194
195	     <dt><code>"nocache"</code> : <atom>boolean</atom></dt>
196	     <dd>This deprecated parameter
197          specifies that data for the view is not taken from the cache, but
198		  read directly from storage. This may entail that future changes that
199		  become visible in the cache are not reflected in this view and that
200		  changes done through this view are not reflected in the cache.
201		  <BR /><strong>Use with caution !</strong>
202          <p><em>This parameter is not supported by all implementations and may be
203          silently ignored !
204          </em></p>
205		 </dd>
206       </dl>
207    </li>
208 </ul>
209
210 <p><member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member>
211 may be unusable. Only an implementation that supports service names that can be
212 used with no further arguments support this method. It should return the
213 same result as if
214 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
215 had been called using an empty sequence of arguments.
216 </p>
217*/
218	interface com::sun::star::lang::XMultiServiceFactory;
219
220
221/** allows controlling or observing the lifetime of the configuration.
222
223 <p>The owner of the provider may dispose of this object
224 using <member scope="com::sun::star::lang">XComponent::dispose()</member>.
225 Note that the default provider is owned by the
226 <type scope="com::sun::star::lang">ServiceManager</type> and should not be
227 disposed of by user code.
228 </p>
229
230 <p>Views created by the provider generally refer to data that is managed by
231  the provider. Therefore, disposing of the provider will cause all objects
232  belonging to these views to be disposed of as well. This does not apply to
233  <em>snapshot</em> views that have their own copy of the data, if available.
234 </p>
235
236*/
237	interface com::sun::star::lang::XComponent;
238
239};
240
241//=============================================================================
242
243}; }; }; };
244
245#endif
246
247
248