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