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