offapi/com/sun/star/configuration/ConfigurationAccess.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 /** provides read access to a fragment of the configuration hierarchy.
  24
  25  <p>Values that are direct or indirect descendants of a root element can be
  26  retrieved and, if themselves objects, navigated. Other interfaces provide
  27  access to information about this element and its context.
  28  Changes to values in the hierarchy can be monitored by event listeners.
  29  </p>
  30
  31  <p>Descendants of this service also implement this service.
  32  </p>
  33
  34  <p>Ultimately the configuration holds values. These values are organized into
  35  a hierarchy using structural elements. The structure is defined in advance in
  36  a schema. Necessary information from the schema is stored in the configuration
  37  repository itself and is accessible through an implementation of this service.
  38  </p>
  39
  40  <p>Two different kinds of structural elements are used in the configuration
  41  hierarchy:
  42  </p>
  43  <dl>
  44     <dt>Sets</dt>
  45         <dd>are dynamic containers of homogeneous elements. Which elements
  46         a <em>set</em> contains can vary. Their names are defined by the
  47         clients that insert them. On the other hand, the <em>type</em> of
  48         the elements is the same for all elements. In the case of elements
  49         that are themselves hierarchy objects, the <em>type</em> includes
  50         the structure of the hierarchy fragment they contain. Such types
  51         are defined in the configuration schema as <em>templates</em>.
  52         </dd>
  53
  54     <dt>Groups</dt>
  55         <dd>are static collections of heterogeneous elements. The names and
  56         types of the elements of a <em>group</em> are completely defined in the
  57         configuration schema. Here each element may be of a different
  58         <em>type</em>, allowing <em>groups</em> that contain a mix of
  59         subobjects and simple values.
  60         </dd>
  61  </dl>
  62
  63  <p>Objects in the configuration hierarchy, for example, implementations of this service,
  64  can thus be classified in the following ways:
  65  </p>
  66  <ul>
  67     <li><em>Container</em> role:
  68         An object that can hold child elements as a <em>set</em> or a <em>group</em>.
  69     </li>
  70     <li><em>Element</em> role:
  71         An object may be an element of a <em>set</em> or a <em>group</em>
  72         or else it may be the root element.
  73     </li>
  74  </ul>
  75
  76  <p>Several types of simple <em>values</em> can be used in the configuration.
  77  In addition to the basic (scalar) types, sequences of the basic types are
  78  supported. The basic types are:
  79  </p>
  80
  81  <ul>
  82     <li><strong>string</strong> can hold a human-readable text.
  83         <p>Values are represented as `string`.</p>
  84         <p>Sequences are represented as `string[]`.</p>
  85         <p>"<em>human-readable</em>" here excludes non-printing characters
  86         except for CR, LF and TAB [Unicode code points 9,10,13].
  87         For binary data, use type <strong>binary</strong> instead.</p>
  88     </li>
  89     <li><strong>boolean</strong> can hold the values `TRUE` or `FALSE`.
  90         <p>Values are represented as `boolean`.
  91         <p>Sequences are represented as `boolean[]`.</p>
  92     </li>
  93     <li><strong>short</strong> can hold a 16-bit signed integer.
  94         <p>Values are represented as `short`.</p>
  95         <p>Sequences are represented as `short[]`.</p>
  96     </li>
  97     <li><strong>int</strong> can hold a 32-bit signed integer.
  98         <p>Values are represented as `long`.</p>
  99         <p>Sequences are represented as `long[]`.</p>
 100     </li>
 101     <li><strong>long</strong> can hold a 64-bit signed integer.
 102         <p>Values are represented as `hyper`.</p>
 103         <p>Sequences are represented as `hyper[]`.</p>
 104     </li>
 105     <li><strong>double</strong> can hold a floating point number.
 106         <p>Values are represented as `double`.</p>
 107         <p>Sequences are represented as `double[]`.</p>
 108     </li>
 109     <li><strong>binary</strong> can hold a sequence of octets.
 110         <p>Values are represented as `byte[]`.</p>
 111         <p>Sequences are represented as `byte[][]`.</p>
 112     </li>
 113  </ul>
 114
 115  <p>Within templates an additional type <strong>any</strong> can occur. When
 116  such a template is used to create a new SetElement, the type
 117  of the element is initially reported as `any` (having no value).
 118  When the value of such an element is first set, it will assume the type used.
 119  </p>
 120
 121  <p>If the schema marks a value as <em>nullable</em> (which is indicated by
 122  attribute com::sun::star::beans::PropertyAttribute::MAYBEVOID ),
 123  its contents may be `NULL`.
 124  </p>
 125
 126  <p>The configuration should support explicit access to default values
 127  (implementing com::sun::star::beans::XPropertyState
 128  and  com::sun::star::beans::XPropertyWithState).
 129  </p>
 130
 131  @see ConfigurationProvider
 132     Root instances of this service can be requested from a
 133     ConfigurationProvider.
 134
 135  @see ConfigurationUpdateAccess
 136     an extended service that includes facilities for modifying
 137     configuration data.
 138 */
 139 published service ConfigurationAccess
 140 {
 141     /** provides interfaces to access child and descendent elements.
 142
 143      <p>An implementation actually implements a specialization of this service,
 144      which depends on its <em>Container</em> role.
 145      </p>
 146
 147      <p>Implementations shall implement exactly one of:</p>
 148      <ul>
 149         <li>SetAccess if this element is a <em>Set</em>.</li>
 150         <li>GroupAccess if this element is a <em>Group</em>.</li>
 151      </ul>
 152      */
 153     service HierarchyAccess;
 154
 155     /** provides interfaces to obtain information about this element and its
 156      role and context in the hierarchy.
 157
 158      <p>An implementation actually implements a specialization of this service,
 159      which depends on its <em>Element</em> role.
 160      </p>
 161
 162      <p>Implementations shall implement exactly one of:</p>
 163      <ul>
 164         <li>AccessRootElement if this element is the
 165             <em>Root</em> of the whole hierarchy. Objects that can be
 166             created directly by a ConfigurationProvider
 167             implement this service.</li>
 168         <li>SetElement if this element may be contained in a
 169             <em>Set</em>.</li>
 170         <li>GroupElement if this element is a child of a
 171             <em>Group</em>.</li>
 172      </ul>
 173
 174      */
 175     service HierarchyElement;
 176
 177     /** specializes HierarchyAccess, if this element is a <em>Set</em>.
 178
 179          <p>This is an alternative to GroupAccess.
 180         </p>
 181     */
 182     [optional] service SetAccess;
 183
 184     /** specializes HierarchyAccess,
 185      if this element is a <em>Group</em>.
 186      <p>This is an alternative to SetAccess.
 187      </p>
 188     */
 189     [optional] service GroupAccess;
 190
 191     /** specializes HierarchyElement,
 192      if this element is the <em>Root</em> of the whole hierarchy.
 193      <p>This is an alternative to SetElement
 194      or GroupElement.
 195      </p>
 196
 197      @see ConfigurationProvider
 198         Instances obtained from a ConfigurationProvider will
 199         implement this version of HierarchyElement.
 200     */
 201     [optional] service AccessRootElement;
 202
 203     /** specializes HierarchyElement,
 204      if this element may be contained in a <em>Set</em>.
 205      <p>This is an alternative to AccessRootElement
 206      or GroupElement.
 207      </p>
 208     */
 209     [optional] service SetElement;
 210
 211     /** specializes HierarchyElement,
 212      if this element is a child of a <em>Group</em>.
 213      <p>This is an alternative to AccessRootElement
 214      or SetElement.
 215      </p>
 216 */
 217     [optional] service GroupElement;
 218 };
 219
 220
 221 }; }; }; };
 222
 223 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */