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

   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
  40 module 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  */
  80 published 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