<html> <head> <title>Service ConfigurationProvider</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../idl.css"> </head> <body> <div id="adc-idlref"> <a name="_top_"> </a><table class="navimain" border="0" cellpadding="3"> <tr> <td class="navimain"><a href="../module-ix.html" class="navimain">Overview</a></td> <td class="navimain"><a href="module-ix.html" class="navimain">Module</a></td> <td class="navimain"><a href="ConfigurationProvider-xref.html" class="navimain">Use</a></td> <td class="navimain"><a href="#devmanual" class="navimain">Devguide</a></td> <td class="navimain"><a href="../../../../index-files/index-1.html" class="navimain">Index</a></td> </tr> </table> <table class="navisub" border="0" cellpadding="0"> <tr> <td class="navisub">Included Services</td> <td class="navisub"><a href="#ExportedInterfaces" class="navisub">Exported Interfaces</a></td> <td class="navisub">Properties' Summary</td> <td class="navisub">Properties' Details</td> </tr> </table> <hr> <table border="0" width="100%" cellpadding="5" cellspacing="3" class="title-table" style="margin-bottom:6pt;"> <tr> <td><p class="namechain"><a href="../../../../module-ix.html" class="namechain">::</a> <a href="../../../module-ix.html" class="namechain">com</a> :: <a href="../../module-ix.html" class="namechain">sun</a> :: <a href="../module-ix.html" class="namechain">star</a> :: <a href="module-ix.html" class="namechain">configuration</a> :: </p> </td> </tr> <tr> <td class="title">service ConfigurationProvider</td> </tr> <tr> <td><dl> <dt><b>Description</b></dt> <dd>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. </dd> <dd><p>An implementation is usually obtained from a ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/ServiceManager.html">ServiceManager</a>. The arguments passed to ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiComponentFactory.html">XMultiComponentFactory</a>::<a href="../lang/XMultiComponentFactory.html#createInstanceWithContextAndArguments">createInstanceWithContextAndArguments()</a> select the configuration data source. Arguments must be provided as ::com::sun::star::<a href="../beans/module-ix.html">beans</a>::<a href="../beans/NamedValue.html">NamedValue</a> or ::com::sun::star::<a href="../beans/module-ix.html">beans</a>::<a href="../beans/PropertyValue.html">PropertyValue</a>. 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 <a href="DefaultProvider.html">DefaultProvider</a> object. </p> <p>Some arguments for ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiServiceFactory.html">XMultiServiceFactory</a>::<a href="../lang/XMultiServiceFactory.html#createInstanceWithArguments">createInstanceWithArguments()</a> 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> </dd> </dl> <a name="devmanual"> </a><dl> <dt><b>Developers Guide</b></dt> <dd><a href="http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/WritingUNO/Disable_Commands#Disabling_Commands_at_Runtime">WritingUNO - Disable Commands - Disabling Commands at Runtime</a></dd> <dd><a href="http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Config/Connecting_to_a_Data_Source">Config - Connecting to a Data Source</a></dd> <dd><a href="http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Config/Object_Model">Config - Object Model</a></dd> </dl> </td> </tr> </table> <hr> <a name="ExportedInterfaces"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle" colspan="2">Exported Interfaces</td> </tr> <tr> <td class="imsum_left">::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiServiceFactory.html">XMultiServiceFactory</a></td> <td class="imsum_right"><dl> <dt><b>Description</b></dt> <dd>allows creating access objects for specific views such as subsets and fragments of the configuration. </dd> <dd><p>The parameter <var>aServiceSpecifier</var> passed to ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiServiceFactory.html">XMultiServiceFactory</a>::<a href="../lang/XMultiServiceFactory.html#createInstanceWithArguments">createInstanceWithArguments()</a> 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 <a href="ConfigurationAccess.html">ConfigurationAccess</a>. To reflect its <em>element role</em> as root of the view, it implements service <a href="AccessRootElement.html">AccessRootElement</a>. </p> <p>Using the second form requests an updatable view of the configuration. The object that is created should implement service <a href="ConfigurationUpdateAccess.html">ConfigurationUpdateAccess</a>. To reflect its <em>element role</em> which includes controlling updates for the whole view, it implements service <a href="UpdateRootElement.html">UpdateRootElement</a>. <BR />If the root element of the view is marked read-only (as indicated by <b>PropertyAttributes::READONLY</b>), the implementation may either raise an exception or return a (read-only) <a href="ConfigurationAccess.html">ConfigurationAccess</a>/<a href="AccessRootElement.html">AccessRootElement</a> instead. </p> <p>The arguments passed to ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiServiceFactory.html">XMultiServiceFactory</a>::<a href="../lang/XMultiServiceFactory.html#createInstanceWithArguments">createInstanceWithArguments()</a> 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 ::com::sun::star::<a href="../beans/module-ix.html">beans</a>::<a href="../beans/PropertyValue.html">PropertyValue</a> or a ::com::sun::star::<a href="../beans/module-ix.html">beans</a>::<a href="../beans/NamedValue.html">NamedValue</a>, 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 <code>string</code>. 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 decendants. </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> : <code>string</code></dt> <dd>specifies the location of the view root in the configuration.</dd> <dt><code>"depth"</code> : <code>short</code></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> : ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/Locale.html">Locale</a></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> : <code>boolean</code></dt> <dd>controls how updates are handled in the cache. If <b>true</b>, 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 <b>false</b>, the cache must operate in <em>write-through</em> mode, where updates are written to persistent storage at once - that is before ::com::sun::star::<a href="../util/module-ix.html">util</a>::<a href="../util/XChangesBatch.html">XChangesBatch</a>::<a href="../util/XChangesBatch.html#commitChanges">commitChanges()</a> 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> : <code>boolean</code></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>::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiServiceFactory.html">XMultiServiceFactory</a>::<a href="../lang/XMultiServiceFactory.html#createInstance">createInstance()</a> 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 ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XMultiServiceFactory.html">XMultiServiceFactory</a>::<a href="../lang/XMultiServiceFactory.html#createInstanceWithArguments">createInstanceWithArguments()</a> had been called using an empty sequence of arguments. </p> </dd> </dl> </td> </tr> <tr> <td class="imsum_left">::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XComponent.html">XComponent</a></td> <td class="imsum_right"><dl> <dt><b>Description</b></dt> <dd>allows controlling or observing the lifetime of the configuration. </dd> <dd><p>The owner of the provider may dispose of this object using ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/XComponent.html">XComponent</a>::<a href="../lang/XComponent.html#dispose">dispose()</a>. Note that the default provider is owned by the ::com::sun::star::<a href="../lang/module-ix.html">lang</a>::<a href="../lang/ServiceManager.html">ServiceManager</a> 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> </dd> </dl> </td> </tr> </table> <br> <a href="#_top_">Top of Page</a><hr size="3"><p class="copyright" align="center">Copyright © 2008 Sun Microsystems, Inc.</p> </div> <!-- id="adc-idlref" --> </body> </html>