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 60module 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*/ 179published 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 266