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 = <Locale for en_US></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