offapi/com/sun/star/configuration/ConfigurationProvider.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
  20
  21 module com { module sun { module star { module configuration {
  22
  23 /** manages one, or more, complete sets of configuration data and serves as a
  24  factory for objects that provide access to a subset of the configuration.
  25
  26  <p>An implementation is usually obtained from a
  27  com::sun::star::lang::ServiceManager. The arguments passed to
  28  com::sun::star::lang::XMultiComponentFactory::createInstanceWithArgumentsAndContext()
  29  select the configuration data source. Arguments must be provided as
  30  com::sun::star::beans::NamedValue
  31  or com::sun::star::beans::PropertyValue.
  32  If the parameters given are incomplete missing values are taken
  33  from the context or the environment. If an instance already exists for the
  34  given set of arguments, the existing instance may be reused.
  35  In particular, instantiating a provider without explicit arguments to access
  36  the default configuration data will always yield the same
  37  com::sun::star::configuration::DefaultProvider object.
  38  </p>
  39  <p>Some arguments for
  40  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  41  may be given default values during creation of this service. In particular
  42  this applies to the parameters <code>"Locale"</code> and <code>"EnableAsync"</code>.
  43  </p>
  44
  45  @deprecated Use theDefaultProvider instead.
  46  */
  47 published service ConfigurationProvider
  48 {
  49 /** allows creating access objects for specific views such as subsets and fragments
  50  of the configuration.
  51
  52  <p>The parameter <var>aServiceSpecifier</var> passed to
  53  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  54  supports at least the service specifiers
  55  <code>"com.sun.star.configuration.ConfigurationAccess"</code> and
  56  <code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>.
  57  </p>
  58
  59  <p>Using the first of these service specifiers requests a read-only view of
  60  the configuration.
  61  The object that is created implements service ConfigurationAccess.
  62  To reflect its <em>element role</em> as root of the view, it implements
  63  service AccessRootElement.
  64  </p>
  65
  66  <p>Using the second form requests an updatable view of the configuration.
  67  The object that is created should implement service
  68  ConfigurationUpdateAccess. To reflect its <em>element role</em>
  69  which includes controlling updates for the whole view, it implements
  70  service UpdateRootElement.
  71  <BR />If the root element of the view is marked read-only (as indicated
  72  by com::sun::star::beans::PropertyAttributes::READONLY),
  73  the implementation may either raise an exception or return a (read-only)
  74  ConfigurationAccess/AccessRootElement instead.
  75  </p>
  76
  77  <p>The arguments passed to
  78  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
  79  in parameter <var>aArguments</var> specify the view of the configuration that
  80  should be created. That is, they determine the subset of elements that can be
  81  accessed starting from the returned object. Each element of the argument
  82  sequence should be a com::sun::star::beans::PropertyValue
  83  or a com::sun::star::beans::NamedValue,
  84  so that the parameters can be identified by name rather than by position.
  85  </p>
  86
  87  <p>What combinations of arguments are supported depends on the service name.
  88  </p>
  89
  90  <p>With both of the standard service-specifiers above, an implementation must
  91  accept a single argument named <code>nodepath</code> of type `string`.
  92  This argument must contain the absolute path to an element of the
  93  configuration. The view that is selected consists of the named element and
  94  all its descendants.
  95  </p>
  96
  97  <p>Other arguments can be used to control the behavior of the view. These
  98  are different for different implementations. Whether and how they are used
  99  may also depend on the configuration store and configuration that were
 100  selected when the provider was created.
 101  </p>
 102
 103  <p>An implementation must ignore unknown arguments.</p>
 104
 105  <p>Some parameters that are commonly supported are:</p>
 106
 107  <ul>
 108     <li>
 109        <strong>Selecting data into a view:</strong>
 110        <dl>
 111          <dt><code>"nodepath"</code> : `string`</dt>
 112          <dd>specifies the location of the view root in the configuration.</dd>
 113          <dt><code>"depth"</code> : `short`</dt>
 114          <dd>specifies that elements of the hierarchy that are more than the given
 115           number of nesting levels away from the root need not be included in the
 116           view.
 117          </dd>
 118          <dt><code>"locale"</code> : com::sun::star::lang::Locale</dt>
 119          <dd>specifies the locale for which localized values should be
 120           retrieved.
 121          </dd>
 122        </dl>
 123
 124        <p><strong>Example:</strong> In the hierarchy
 125 <BR /><pre>
 126  A - B1 - C1
 127    |
 128    - B2 - C2 (localized: de, en, fr, ..)
 129    |    |
 130    |    - C3 - D1
 131    |    |    |
 132    |    |    - D2 - E1
 133    |    |
 134    |    - C4 - D3 - E2 - F1
 135    |    |              |
 136    |    |              - F2
 137    |    |
 138    |    - C5
 139    |
 140    - B3
 141    |
 142    - B4 - C6 - D4 - E3
 143
 144 </pre>
 145          <BR />selecting a view with <code>nodepath = "/A/B2"</code>,
 146          <code>depth = 2</code> and <code>locale = &lt;Locale for en_US&gt;</code>
 147          would result in the tree fragment
 148 <BR /><pre>
 149 (A-) B2 - C2 (en)
 150         |
 151         - C3 - D1
 152         |    |
 153         |    - D2 (..)
 154         |
 155         - C4 - D3 (..)
 156         |
 157         - C5
 158
 159 </pre>
 160        </p>
 161     </li>
 162
 163     <li>
 164        <strong>Controlling cache behavior:</strong> (with providers that
 165         cache configuration data)
 166        <dl>
 167          <dt><code>"enableasync"</code> : `boolean`</dt>
 168          <dd>controls how updates are handled in the cache. If `TRUE`, the
 169           cache may operate in <em>write-back</em> mode, where updates at
 170           first only affect the cache and are written to persistent storage
 171           at some later time. If `FALSE`, the cache must operate in
 172           <em>write-through</em> mode, where updates are written to persistent
 173           storage at once - that is before
 174           com::sun::star::util::XChangesBatch::commitChanges()
 175           returns.
 176           <p><em>This parameter was formerly called <code>"lazywrite"</code>.
 177             The old name should still be supported for compatibility.
 178           </em></p>
 179          </dd>
 180
 181          <dt><code>"nocache"</code> : `boolean`</dt>
 182          <dd>This deprecated parameter
 183           specifies that data for the view is not taken from the cache, but
 184           read directly from storage. This may entail that future changes that
 185           become visible in the cache are not reflected in this view and that
 186           changes done through this view are not reflected in the cache.
 187           <BR /><strong>Use with caution !</strong>
 188           <p><em>This parameter is not supported by all implementations and may be
 189           silently ignored !
 190           </em></p>
 191          </dd>
 192        </dl>
 193     </li>
 194  </ul>
 195
 196  <p>com::sun::star::lang::XMultiServiceFactory::createInstance()
 197  may be unusable. Only an implementation that supports service names that can be
 198  used with no further arguments support this method. It should return the
 199  same result as if
 200  com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
 201  had been called using an empty sequence of arguments.
 202  </p>
 203 */
 204     interface com::sun::star::lang::XMultiServiceFactory;
 205
 206
 207 /** allows controlling or observing the lifetime of the configuration.
 208
 209  <p>The owner of the provider may dispose of this object
 210  using com::sun::star::lang::XComponent::dispose().
 211  Note that the default provider is owned by the
 212  com::sun::star::lang::ServiceManager and should not be
 213  disposed of by user code.
 214  </p>
 215
 216  <p>Views created by the provider generally refer to data that is managed by
 217   the provider. Therefore, disposing of the provider will cause all objects
 218   belonging to these views to be disposed of as well. This does not apply to
 219   <em>snapshot</em> views that have their own copy of the data, if available.
 220  </p>
 221
 222 */
 223     interface com::sun::star::lang::XComponent;
 224
 225 };
 226
 227
 228 }; }; }; };
 229
 230
 231 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */