| /************************************************************** | |
| * | |
| * 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 | |
| * | |
| * Unless required by applicable law or agreed to in writing, | |
| * software distributed under the License is distributed on an | |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| * KIND, either express or implied. See the License for the | |
| * specific language governing permissions and limitations | |
| * under the License. | |
| * | |
| *************************************************************/ | |
| #ifndef __com_sun_star_configuration_ConfigurationProvider_idl__ | |
| #define __com_sun_star_configuration_ConfigurationProvider_idl__ | |
| #ifndef __com_sun_star_lang_XMultiServiceFactory_idl__ | |
| #include <com/sun/star/lang/XMultiServiceFactory.idl> | |
| #endif | |
| #ifndef __com_sun_star_lang_XComponent_idl__ | |
| #include <com/sun/star/lang/XComponent.idl> | |
| #endif | |
| //============================================================================= | |
| 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> | |
| */ | |
| 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 |