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