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