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