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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_configuration_AdministrationProvider_idl__
  20 #define __com_sun_star_configuration_AdministrationProvider_idl__
  21
  22 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  23 #include <com/sun/star/lang/XComponent.idl>
  24
  25
  26 module com { module sun { module star { module configuration {
  27
  28 /** manages one, or more, complete sets of configuration data for
  29  administrative purposes and serves as a factory for objects that
  30  provide access to subsets of these shared configurations.
  31
  32  <p>Shared sets of configuration data usually serve to provide defaults,
  33  which are used if no individual settings are present. Depending on the data
  34  store multiple layers of defaults may be combined with a user-specific layer
  35  to make up the final configuration.
  36  </p>
  37  <p>Many aspects of the supported behavior depend strongly on the underlying
  38  data store and on the administrative structures it defines. With some data
  39  stores this service also enables access to individual user's configuration
  40  data by an administrator.
  41  </p>
  42  <p>On the other hand, in the simplest model there is only a single layer of
  43  default data which is accessible through this service.
  44  </p>
  45  <p>An implementation is usually obtained from a
  46  com::sun::star::lang::ServiceManager. The arguments passed to
  47  com::sun::star::lang::XMultiComponentFactory::createInstanceWithContextAndArguments()
  48  select the configuration data source. They may also define the scope of
  49  administrable data or contain credentials to be used to authorize the
  50  administrative access. Missing parameters may be filled in
  51  from the context or the environment.
  52  </p>
  53
  54  @see com::sun::star::configuration::ConfigurationProvider
  55     Offers the same services and creates the same accessor objects as this
  56     service, but accesses the personal configuration.
  57
  58     <p>A  ConfigurationProvider provides access to the personal
  59     layer of configuration data of the current user context. It should in
  60     most cases be used when <em>using</em> the configuration data, although
  61     for most contexts a AdministrationProvider can be used as
  62     a drop-in replacement.
  63     </p>
  64  */
  65 published service AdministrationProvider
  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  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  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 ConfigurationAccess.
  80  To reflect its <em>element role</em> as root of the view, it implements
  81  service AccessRootElement.
  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  ConfigurationUpdateAccess. To reflect its <em>element role</em>
  87  which includes controlling updates for the whole view, it implements
  88  service UpdateRootElement.
  89  <BR />If the root element of the view is marked read-only (as indicated
  90  by com::sun::star::beans::PropertyAttributes::READONLY),
  91  the implementation may either raise an exception or return a (read-only)
  92  ConfigurationAccess/AccessRootElement instead.
  93  </p>
  94
  95  <p>The arguments passed to
  96  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  97  in parameter <var>aArguments</var> specify the administrative entity for which
  98  data should be administered. In other words they determine the layer to which
  99  changes will apply. They also specify the view of that configuration that
 100  should be created. That is, they determine the subset of elements that can be
 101  accessed starting from the returned object. Each element of the argument
 102  sequence should be a com::sun::star::beans::PropertyValue
 103  or a com::sun::star::beans::NamedValue,
 104  so that the parameters can be identified by name rather than by position.
 105  </p>
 106
 107  <p>What combinations of arguments are supported depends on the service name
 108  and on the data store being administered.
 109  </p>
 110
 111  <p>With both of the standard service-specifiers above, an implementation must
 112  accept a single argument named <code>nodepath</code> of type `string`.
 113  This argument must contain the absolute path to an element of the
 114  configuration. The view that is selected consists of the named element and
 115  all its descendants. The administrative entity is the default for the
 116  AdministrationProvider. Usually this is the largest entity
 117  encompassing all entities accessible from this instance. In other words this
 118  can be used to influence as global a scope as possible.
 119  </p>
 120
 121  <p>Other arguments can be used to select a more specific entity and to control
 122  the behavior of the view. These are different for different implementations
 123  and data stores. Whether and how they are used may also depend on properties
 124  that were selected when the provider was created.
 125  </p>
 126
 127  <p>An implementation may ignore unknown arguments.</p>
 128
 129  <p>Some parameters that are commonly supported are described for service
 130  ConfigurationProvider.
 131  </p>
 132  <p>One notable difference exists for parameter <code>"Locale"</code>. For a
 133  ConfigurationProvider the default behavior usually is to select
 134  the locale set up for the user. But this service by default gets data for all
 135  locales for which data is present. Locale-dependent values in this case are
 136  replaced by a SetAccess using the language names as accessors.
 137  This also allows targeted setting of values for selected locales.
 138  This behavior can be requested explicitly by specifying a special argument
 139  value <code>locale = "*"</code>.
 140  </p>
 141
 142  <p>com::sun::star::lang::XMultiServiceFactory::createInstance()
 143  may be unusable. Only an implementation that supports service names that can be
 144  used with no further arguments support this method. It should return the
 145  same result as if
 146  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
 147  had been called using an empty sequence of arguments.
 148  </p>
 149 */
 150     interface com::sun::star::lang::XMultiServiceFactory;
 151
 152
 153 /** allows controlling or observing the lifetime of the configuration.
 154
 155  <p>The owner of the provider may dispose of this object
 156  using com::sun::star::lang::XComponent::dispose().
 157  </p>
 158
 159  <p>Views created by the provider generally refer to data that is managed by
 160   the provider. Therefore, disposing of the provider will cause all objects
 161   belonging to these views to be disposed of as well. This does not apply to
 162   <em>snapshot</em> views that have their own copy of the data, if available.
 163  </p>
 164
 165 */
 166     interface com::sun::star::lang::XComponent;
 167
 168 };
 169
 170
 171 }; }; }; };
 172
 173 #endif
 174
 175
 176 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */