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