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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: AdministrationProvider.idl,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_configuration_ConfigurationProvider_idl__
  31 #define __com_sun_star_configuration_ConfigurationProvider_idl__
  32
  33 #ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
  34 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_lang_XComponent_idl__
  38 #include <com/sun/star/lang/XComponent.idl>
  39 #endif
  40
  41 //=============================================================================
  42
  43 module com { module sun { module star { module configuration {
  44
  45 //=============================================================================
  46 /** manages one, or more, complete sets of configuration data for
  47  administrative puposes and serves as a factory for objects that
  48  provide access to subsets of these shared configurations.
  49
  50  <p>Shared sets of configuration data usually serve to provide defaults,
  51  which are used if no individual settings are present. Depending on the data
  52  store multiple layers of defaults may be combined with a user-specific layer
  53  to make up the final configuration.
  54  </p>
  55  <p>Many aspects of the supported behavior depend strongly on the underlying
  56  data store and on the administrative structures it defines. With some data
  57  stores this service also enables access to individual users' configuration
  58  data by an administrator.
  59  </p>
  60  <p>On the other hand, in the simplest model there is only a single layer of
  61  default data which is accessible through this service.
  62  </p>
  63  <p>An implementation is usually obtained from a
  64  <type scope="com::sun::star::lang">ServiceManager</type>. The arguments passed to
  65  <member scope="com::sun::star::lang">XMultiComponentFactory::createInstanceWithContextAndArguments()</member>
  66  select the configuration data source. They may also define the scope of
  67  administrable data or contain credentials to be used to authorize the
  68  administrative access. Missing parameters may be filled in
  69  from the context or the environment.
  70  </p>
  71
  72  @see com::sun::star::configuration::ConfigurationProvider
  73     Offers the same services and creates the same accessor objects as this
  74     service, but accesses the personal configuration.
  75
  76     <p>A <type> ConfigurationProvider</type> provides access to the personal
  77     layer of configuration data of the current user context. It should in
  78     most cases be used when <em>using</em> the configuration data, although
  79     for most contexts a <type>AdministrationProvider</type> can be used as
  80     a drop-in replacement.
  81     </p>
  82  */
  83 published service AdministrationProvider
  84 {
  85 /** allows creating access objects for specific views such as subsets and fragments
  86  of the configuration.
  87
  88  <p>The parameter <var>aServiceSpecifier</var> passed to
  89  <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
  90  supports at least the service specifiers
  91  <code>"com.sun.star.configuration.ConfigurationAccess"</code> and
  92  <code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>.
  93  </p>
  94
  95  <p>Using the first of these service specifiers requests a read-only view of
  96  the configuration.
  97  The object that is created implements service <type>ConfigurationAccess</type>.
  98  To reflect its <em>element role</em> as root of the view, it implements
  99  service <type>AccessRootElement</type>.
 100  </p>
 101
 102  <p>Using the second form requests an updatable view of the configuration.
 103  The object that is created should implement service
 104  <type>ConfigurationUpdateAccess</type>. To reflect its <em>element role</em>
 105  which includes controlling updates for the whole view, it implements
 106  service <type>UpdateRootElement</type>.
 107  <BR />If the root element of the view is marked read-only (as indicated
 108  by <const scope="com::sun::star::beans">PropertyAttributes::READONLY</const>),
 109  the implementation may either raise an exception or return a (read-only)
 110  <type>ConfigurationAccess</type>/<type>AccessRootElement</type> instead.
 111  </p>
 112
 113  <p>The arguments passed to
 114  <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
 115  in parameter <var>aArguments</var> specify the administrative entity for which
 116  data should be administered. In other words they determine the layer to which
 117  changes will apply. They also specify the view of that configuration that
 118  should be created. That is, they determine the subset of elements that can be
 119  accessed starting from the returned object. Each element of the argument
 120  sequence should be a <type scope="com::sun::star::beans">PropertyValue</type>
 121  or a <type scope="com::sun::star::beans">NamedValue</type>,
 122  so that the parameters can be identified by name rather than by position.
 123  </p>
 124
 125  <p>What combinations of arguments are supported depends on the service name
 126  and on the data store being administered.
 127  </p>
 128
 129  <p>With both of the standard service-specifiers above, an implementation must
 130  accept a single argument named <code>nodepath</code> of type <atom>string</atom>.
 131  This argument must contain the absolute path to an element of the
 132  configuration. The view that is selected consists of the named element and
 133  all its decendants. The administrative entity is the default for the
 134  <type>AdministrationProvider</type>. Usually this is the largest entity
 135  encompassing all entities accessible from this instance. In other words this
 136  can be used to influence as global a scope as possible.
 137  </p>
 138
 139  <p>Other arguments can be used to select a more specific entity and to control
 140  the behavior of the view. These are different for different implementations
 141  and data stores. Whether and how they are used may also depend on properties
 142  that were selected when the provider was created.
 143  </p>
 144
 145  <p>An implementation may ignore unknown arguments.</p>
 146
 147  <p>Some parameters that are commonly supported are described for service
 148  <type>ConfigurationProvider</type>.
 149  </p>
 150  <p>One notable difference exists for parameter <code>"Locale"</code>. For a
 151  <type>ConfigurationProvider</type> the default behavior usually is to select
 152  the locale set up for the user. But this service by default gets data for all
 153  locales for which data is present. Locale-dependent values in this case are
 154  replaced by a <type>SetAccess</type> using the language names as accessors.
 155  This also allows targetted setting of values for selected locales.
 156  This behavior can be requested explicitly by specifing a special argument
 157  value <code>locale = "*"</code>.
 158  </p>
 159
 160  <p><member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member>
 161  may be unusable. Only an implementation that supports service names that can be
 162  used with no further arguments support this method. It should return the
 163  same result as if
 164  <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
 165  had been called using an empty sequence of arguments.
 166  </p>
 167 */
 168     interface com::sun::star::lang::XMultiServiceFactory;
 169
 170
 171 /** allows controlling or observing the lifetime of the configuration.
 172
 173  <p>The owner of the provider may dispose of this object
 174  using <member scope="com::sun::star::lang">XComponent::dispose()</member>.
 175  </p>
 176
 177  <p>Views created by the provider generally refer to data that is managed by
 178   the provider. Therefore, disposing of the provider will cause all objects
 179   belonging to these views to be disposed of as well. This does not apply to
 180   <em>snapshot</em> views that have their own copy of the data, if available.
 181  </p>
 182
 183 */
 184     interface com::sun::star::lang::XComponent;
 185
 186 };
 187
 188 //=============================================================================
 189
 190 }; }; }; };
 191
 192 #endif
 193
 194