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 for 44 administrative puposes and serves as a factory for objects that 45 provide access to subsets of these shared configurations. 46 47 <p>Shared sets of configuration data usually serve to provide defaults, 48 which are used if no individual settings are present. Depending on the data 49 store multiple layers of defaults may be combined with a user-specific layer 50 to make up the final configuration. 51 </p> 52 <p>Many aspects of the supported behavior depend strongly on the underlying 53 data store and on the administrative structures it defines. With some data 54 stores this service also enables access to individual users' configuration 55 data by an administrator. 56 </p> 57 <p>On the other hand, in the simplest model there is only a single layer of 58 default data which is accessible through this service. 59 </p> 60 <p>An implementation is usually obtained from a 61 <type scope="com::sun::star::lang">ServiceManager</type>. The arguments passed to 62 <member scope="com::sun::star::lang">XMultiComponentFactory::createInstanceWithContextAndArguments()</member> 63 select the configuration data source. They may also define the scope of 64 administrable data or contain credentials to be used to authorize the 65 administrative access. Missing parameters may be filled in 66 from the context or the environment. 67 </p> 68 69 @see com::sun::star::configuration::ConfigurationProvider 70 Offers the same services and creates the same accessor objects as this 71 service, but accesses the personal configuration. 72 73 <p>A <type> ConfigurationProvider</type> provides access to the personal 74 layer of configuration data of the current user context. It should in 75 most cases be used when <em>using</em> the configuration data, although 76 for most contexts a <type>AdministrationProvider</type> can be used as 77 a drop-in replacement. 78 </p> 79 */ 80published service AdministrationProvider 81{ 82/** allows creating access objects for specific views such as subsets and fragments 83 of the configuration. 84 85 <p>The parameter <var>aServiceSpecifier</var> passed to 86 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member> 87 supports at least the service specifiers 88 <code>"com.sun.star.configuration.ConfigurationAccess"</code> and 89 <code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>. 90 </p> 91 92 <p>Using the first of these service specifiers requests a read-only view of 93 the configuration. 94 The object that is created implements service <type>ConfigurationAccess</type>. 95 To reflect its <em>element role</em> as root of the view, it implements 96 service <type>AccessRootElement</type>. 97 </p> 98 99 <p>Using the second form requests an updatable view of the configuration. 100 The object that is created should implement service 101 <type>ConfigurationUpdateAccess</type>. To reflect its <em>element role</em> 102 which includes controlling updates for the whole view, it implements 103 service <type>UpdateRootElement</type>. 104 <BR />If the root element of the view is marked read-only (as indicated 105 by <const scope="com::sun::star::beans">PropertyAttributes::READONLY</const>), 106 the implementation may either raise an exception or return a (read-only) 107 <type>ConfigurationAccess</type>/<type>AccessRootElement</type> instead. 108 </p> 109 110 <p>The arguments passed to 111 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member> 112 in parameter <var>aArguments</var> specify the administrative entity for which 113 data should be administered. In other words they determine the layer to which 114 changes will apply. They also specify the view of that configuration that 115 should be created. That is, they determine the subset of elements that can be 116 accessed starting from the returned object. Each element of the argument 117 sequence should be a <type scope="com::sun::star::beans">PropertyValue</type> 118 or a <type scope="com::sun::star::beans">NamedValue</type>, 119 so that the parameters can be identified by name rather than by position. 120 </p> 121 122 <p>What combinations of arguments are supported depends on the service name 123 and on the data store being administered. 124 </p> 125 126 <p>With both of the standard service-specifiers above, an implementation must 127 accept a single argument named <code>nodepath</code> of type <atom>string</atom>. 128 This argument must contain the absolute path to an element of the 129 configuration. The view that is selected consists of the named element and 130 all its decendants. The administrative entity is the default for the 131 <type>AdministrationProvider</type>. Usually this is the largest entity 132 encompassing all entities accessible from this instance. In other words this 133 can be used to influence as global a scope as possible. 134 </p> 135 136 <p>Other arguments can be used to select a more specific entity and to control 137 the behavior of the view. These are different for different implementations 138 and data stores. Whether and how they are used may also depend on properties 139 that were selected when the provider was created. 140 </p> 141 142 <p>An implementation may ignore unknown arguments.</p> 143 144 <p>Some parameters that are commonly supported are described for service 145 <type>ConfigurationProvider</type>. 146 </p> 147 <p>One notable difference exists for parameter <code>"Locale"</code>. For a 148 <type>ConfigurationProvider</type> the default behavior usually is to select 149 the locale set up for the user. But this service by default gets data for all 150 locales for which data is present. Locale-dependent values in this case are 151 replaced by a <type>SetAccess</type> using the language names as accessors. 152 This also allows targetted setting of values for selected locales. 153 This behavior can be requested explicitly by specifing a special argument 154 value <code>locale = "*"</code>. 155 </p> 156 157 <p><member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member> 158 may be unusable. Only an implementation that supports service names that can be 159 used with no further arguments support this method. It should return the 160 same result as if 161 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member> 162 had been called using an empty sequence of arguments. 163 </p> 164*/ 165 interface com::sun::star::lang::XMultiServiceFactory; 166 167 168/** allows controlling or observing the lifetime of the configuration. 169 170 <p>The owner of the provider may dispose of this object 171 using <member scope="com::sun::star::lang">XComponent::dispose()</member>. 172 </p> 173 174 <p>Views created by the provider generally refer to data that is managed by 175 the provider. Therefore, disposing of the provider will cause all objects 176 belonging to these views to be disposed of as well. This does not apply to 177 <em>snapshot</em> views that have their own copy of the data, if available. 178 </p> 179 180*/ 181 interface com::sun::star::lang::XComponent; 182 183}; 184 185//============================================================================= 186 187}; }; }; }; 188 189#endif 190 191 192