main/offapi/com/sun/star/configuration/AdministrationProvider.idl

/**************************************************************
 * 
 * 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 for 
 administrative puposes and serves as a factory for objects that
 provide access to subsets of these shared configurations.
 
 <p>Shared sets of configuration data usually serve to provide defaults, 
 which are used if no individual settings are present. Depending on the data 
 store multiple layers of defaults may be combined with a user-specific layer 
 to make up the final configuration. 
 </p>
 <p>Many aspects of the supported behavior depend strongly on the underlying 
 data store and on the administrative structures it defines. With some data 
 stores this service also enables access to individual users' configuration 
 data by an administrator. 
 </p>
 <p>On the other hand, in the simplest model there is only a single layer of 
 default data which is accessible through this service. 
 </p>
 <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. They may also define the scope of 
 administrable data or contain credentials to be used to authorize the 
 administrative access. Missing parameters may be filled in  
 from the context or the environment.  
 </p>

 @see com::sun::star::configuration::ConfigurationProvider
	Offers the same services and creates the same accessor objects as this 
	service, but accesses the personal configuration.
	
	<p>A <type> ConfigurationProvider</type> provides access to the personal 
	layer of configuration data of the current user context. It should in 
	most cases be used when <em>using</em> the configuration data, although
	for most contexts a <type>AdministrationProvider</type> can be used as 
	a drop-in replacement. 
	</p> 
 */
published service AdministrationProvider
{
/** 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 administrative entity for which 
 data should be administered. In other words they determine the layer to which 
 changes will apply. They also specify the view of that 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 
 and on the data store being administered.
 </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 decendants. The administrative entity is the default for the 
 <type>AdministrationProvider</type>. Usually this is the largest entity 
 encompassing all entities accessible from this instance. In other words this 
 can be used to influence as global a scope as possible. 
 </p>
 
 <p>Other arguments can be used to select a more specific entity and to control 
 the behavior of the view. These are different for different implementations 
 and data stores. Whether and how they are used may also depend on properties 
 that were selected when the provider was created.
 </p>

 <p>An implementation may ignore unknown arguments.</p>

 <p>Some parameters that are commonly supported are described for service 
 <type>ConfigurationProvider</type>.
 </p>
 <p>One notable difference exists for parameter <code>"Locale"</code>. For a 
 <type>ConfigurationProvider</type> the default behavior usually is to select 
 the locale set up for the user. But this service by default gets data for all 
 locales for which data is present. Locale-dependent values in this case are 
 replaced by a <type>SetAccess</type> using the language names as accessors. 
 This also allows targetted setting of values for selected locales. 
 This behavior can be requested explicitly by specifing a special argument 
 value <code>locale = "*"</code>.
 </p>

 <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>.
 </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