New services describing the configuration object taxonomy

16 files changed, 2592 insertions, 185 deletions

diff --git a/offapi/com/sun/star/configuration/AccessRootElement.idl b/offapi/com/sun/star/configuration/AccessRootElement.idl
new file mode 100644
index 000000000000..18014a533eed
--- /dev/null
+++ b/offapi/com/sun/star/configuration/AccessRootElement.idl
@@ -0,0 +1,210 @@
+/*************************************************************************
+ *
+ *  $RCSfile: AccessRootElement.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_AccessRootElement_idl__
+#define __com_sun_star_configuration_AccessRootElement_idl__
+
+#ifndef __com_sun_star_configuration_HierarchyElement_idl__
+#include <com/sun/star/configuration/HierarchyElement.idl>
+#endif
+
+#ifndef __com_sun_star_lang_XComponent_idl__
+#include <com/sun/star/lang/XComponent.idl>
+#endif
+
+#ifndef __com_sun_star_lang_XLocalizable_idl__
+#include <com/sun/star/lang/XLocalizable.idl>
+#endif
+
+#ifndef __com_sun_star_util_XChangesNotifier_idl__
+#include <com/sun/star/util/XChangesNotifier.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides information about the root element of a (by name) hierarchy
+ and about the hierarchy as a whole.
+
+ <p>Provides information about the element and the whole hierarchy.
+ Allows controlling the lifetime of the hierarchy.
+ Allows observing changes in the hierarchy as a whole.
+ </p>
+
+ <p>When access to a hierarchy is first obtained from a factory or provider,
+ this is the initial object that is created by the factory.
+ It represents the <em>root</em> of (the accessible part of) the hierarchy.
+ </p>
+
+ <p><em><strong>NOTE:</strong> In this description 'hierarchy' may actually
+ designate a part or fragment of a larger hierarchy. It is that part that is
+ rooted in the element represented by an implementation of this service
+ and that is accessible starting from this element.</em>
+ </p>
+
+ <p>Generally it is not possible to navigate the 'surroundings' (if any) of this
+ element, so <type scope="com::sun::star::container">XChild</type> is not
+ supported.
+ </p>
+
+ @see com::sun::star::configuration::UpdateRootElement
+    Implementations that support modifying data in the hierarchy
+    generally implement service UpdateRootElement.
+
+ @see com::sun::star::configuration::SetElement
+    A complementary service, for children of a dynamic homogeneous container.
+
+ @see com::sun::star::configuration::GroupElement
+    A complementary service, for children of a static heterogeneous collection.
+
+ @see com::sun::star::configuration::ConfigurationProvider
+    Objects provided by a <type>ConfigurationProvider</type> implement this service.
+
+*/
+service AccessRootElement
+{
+/** is the basic service for accessing information about an element in the
+ hierarchy.
+*/
+    service HierarchyElement;
+
+/** allows controlling or observing the lifetime of the whole hierarchy.
+
+ <p>The owner of the hierarchy may dispose this object
+ (using <member scope="com::sun::star::lang">XComponent::dispose</member>).
+ As this object owns its child elements and (recursively) the whole hierarchy,
+ any descendant elements obtained (directly or indirectly) from this object
+ will also be disposed. Disposing the object does not affect a persistent
+ representation of the hierarchy.
+ </p>
+
+ <p>When an implementation is obtained from a factory or provider, ownership
+ of is usually transferred to the client. See the documentation
+ of the particular provider or factory service for details.
+ </p>
+
+ <p>The provider of this object may still dispose this object, when the
+ lifetime of the provider ends itself or if this objects represents
+ (the root of) only a fragment of an enclosing hierarchy and
+ this fragment is removed from the complete hierarchy by an outside source,
+ </p>
+
+ <p>Clients may register a <type scope="com::sun::star::lang">XEventListener</type>
+ to be notified when the object is disposed (for either cause).
+ </p>
+*/
+    interface com::sun::star::lang::XComponent;
+
+/** allows registering listeners that observe the whole hierarchy.
+
+ <p>A client can register a
+ <type scope="com::sun::star::util">XChangesListener</type>,
+ which will receive notifications for any changes within the
+ hierarchy (fragment) this object represents.
+ </p>
+
+ <p>An implementation will collect as many changes as possible into a single
+ <type scope="com::sun::star::util">ChangesEvent</type>. For Example:
+ </p>
+
+ <p>
+ If <member scope="com::sun::star::beans">XMultiPropertySet::setPropertyValues</member>
+ or <member scope="com::sun::star::beans">XMultiHierarchicalPropertySet::setHierarchicalPropertyValues</member>
+ is used on an element of the hierarchy to change multiple values within
+ the hierarchy, all changes will be notified with a single event.
+ </p>
+
+ <p>If an outside source uses
+ <member scope="com::sun::star::util">XChangesBatch::commitChanges</member>
+ on an overlapping hierarchy access, all relevant changes will be notified
+ with a single event.
+ </p>
+
+ @ see UpdateRootElement
+ @ see com::sun::star::util::XChangesBatch
+*/
+    interface com::sun::star::util::XChangesNotifier;
+
+/** provides access to the locale that applies to locale-dependent data
+ in this hierarchy. [optional]
+
+ <p>This interface may be missing, if the implementation does not support
+ locale-dependent data in the hierarchy or if the (partial) hierarchy rooted
+ in this object does not contain any locale-dependent elements.
+ </p>
+
+ <p><em>Changing the locale is generally not supported.</em> If it is supported
+ there is no guarantee that values already loaded into the hierarchy or an
+ application cache are refreshed to reflect the new locale. Use of
+ <member scope="com::sun::star::lang">XLocalizable::setLocale</member>
+ is therefore not recommended.
+ </p>
+*/
+    [optional] interface com::sun::star::lang::XLocalizable;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/ConfigurationAccess.idl b/offapi/com/sun/star/configuration/ConfigurationAccess.idl
index 369a44f801cf..29aae60b2351 100644
--- a/offapi/com/sun/star/configuration/ConfigurationAccess.idl
+++ b/offapi/com/sun/star/configuration/ConfigurationAccess.idl
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: ConfigurationAccess.idl,v $
  *
- *  $Revision: 1.5 $
+ *  $Revision: 1.6 $
  *
- *  last change: $Author: mi $ $Date: 2001-01-23 10:08:05 $
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -61,171 +61,229 @@
 #ifndef __com_sun_star_configuration_ConfigurationAccess_idl__
 #define __com_sun_star_configuration_ConfigurationAccess_idl__
 
-#ifndef __com_sun_star_container_XNameAccess_idl__
-#include <com/sun/star/container/XNameAccess.idl>
+#ifndef __com_sun_star_configuration_HierarchyAccess_idl__
+#include <com/sun/star/configuration/HierarchyAccess.idl>
 #endif
 
-#ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__
-#include <com/sun/star/container/XHierarchicalNameAccess.idl>
+#ifndef __com_sun_star_configuration_HierarchyElement_idl__
+#include <com/sun/star/configuration/HierarchyElement.idl>
 #endif
 
-#ifndef __com_sun_star_container_XChild_idl__
-#include <com/sun/star/container/XChild.idl>
+#ifndef __com_sun_star_configuration_SetAccess_idl__
+#include <com/sun/star/configuration/SetAccess.idl>
 #endif
 
-#ifndef __com_sun_star_container_XNamed_idl__
-#include <com/sun/star/container/XNamed.idl>
+#ifndef __com_sun_star_configuration_GroupAccess_idl__
+#include <com/sun/star/configuration/GroupAccess.idl>
 #endif
 
-#ifndef __com_sun_star_container_XHierarchicalName_idl__
-#include <com/sun/star/container/XHierarchicalName.idl>
+#ifndef __com_sun_star_configuration_AccessRootElement_idl__
+#include <com/sun/star/configuration/AccessRootElement.idl>
 #endif
 
-#ifndef __com_sun_star_container_XContainer_idl__
-#include <com/sun/star/container/XContainer.idl>
+#ifndef __com_sun_star_configuration_SetElement_idl__
+#include <com/sun/star/configuration/SetElement.idl>
 #endif
 
-#ifndef __com_sun_star_util_XChangesNotifier_idl__
-#include <com/sun/star/util/XChangesNotifier.idl>
+#ifndef __com_sun_star_configuration_GroupElement _idl__
+#include <com/sun/star/configuration/GroupElement.idl>
 #endif
 
-#ifndef __com_sun_star_lang_XInitialization_idl__
-#include <com/sun/star/lang/XInitialization.idl>
-#endif
-
-#ifndef __com_sun_star_lang_XLocalizable_idl__
-#include <com/sun/star/lang/XLocalizable.idl>
-#endif
-
-#ifndef __com_sun_star_beans_XExactName_idl__
-#include <com/sun/star/beans/XExactName.idl>
-#endif
-
-#ifndef __com_sun_star_beans_XPropertySet_idl__
-#include <com/sun/star/beans/XPropertySet.idl>
-#endif
-
-#ifndef __com_sun_star_beans_XMultiPropertySet_idl__
-#include <com/sun/star/beans/XMultiPropertySet.idl>
-#endif
-
-#ifndef __com_sun_star_beans_XPropertyState_idl__
-#include <com/sun/star/beans/XPropertyState.idl>
-#endif
-
-#ifndef __com_sun_star_beans_XPropertyAccess_idl__
-#include <com/sun/star/beans/XPropertyAccess.idl>
-#endif
-
-
 //=============================================================================
 
 module com { module sun { module star { module configuration {
 
 //=============================================================================
-/** provides read-only access to a subtree of the configuration hierarchy.
- Values that are direct or indirect descendants of this node can be retrieved,
- non-value subnodes can be navigated using container interfaces.
- Other interfaces provide access to information about this node.
- Changes to values in the subtree can be monitored by event listeners.
-
-    @guarantees:<B>
-    -thread safe
-
-    @author Joerg Barfurth
-    @version 1.0 2000/06/01
+/** provides (read) access to a fragment of the configuration hierarchy.
+
+ <p>Values that are direct or indirect descendants of a root element can be
+ retrieved and, if themselves objects, navigated. Other interfaces provide
+ access to information about this element and its context.
+ Changes to values in the hierarchy can be monitored by event listeners.
+ </p>
+
+ <p>Descendants of this service also implement this service
+ (and so on recursively).
+ </p>
+
+ <p>Ultimately the configuration holds values. These values are organized into
+ a hierarchy using structural elements. The structure is defined in advance in
+ a schema. Necessary information from the schema is stored in the configuration
+ repository itself, and is accessible through an implementation of this service.
+ </p>
+
+ <p>Two different kinds of structural elements are used in the configuration
+ hierarchy:
+ </p>
+ <dl>
+    <dt>Sets</dt>
+        <dd>are dynamic containers of homogeneous elements. Which elements
+        a <em>set</em> contains can vary; their names are defined by the
+        clients that insert them. On the other hand the <em>type</em> of
+        the elements is the same for all elements. In the case of elements
+        that are themselves hierarchy objects, the <em>type</em> includes
+        the structure of the hierarchy fragment they contain. Such types
+        are defined in the configuration schema as <p>templates</p>.
+        </dd>
+
+    <dt>Groups</dt>
+        <dd>are static collections of heterogeneous elements. The names and
+        types of the elements a <em>group</em> are completely defined in the
+        configuration schema. But here each element may be of a different
+        <em>type</em>, allowing even <em>groups</em> that contain a mix of
+        subobjects and simple values.
+        </dd>
+ </dl>
+
+ <p>Objects in the configuration hierarchy (i.e. implementations of this service)
+ can thus be classified in the following ways:
+ </p>
+ <ul>
+    <li><em>Container</em> role:
+        An object can hold child elements as a <em>set</em> or a <em>group</em>.
+    </li>
+    <li><em>Element</em> role:
+        An object may be an element of a <em>set</em> or a <em>group</em>
+        or else it may be the root element.
+    </li>
+ </ul>
+
+ <p>Several types of simple <em>Values</em> can be used in the configuration.
+ In addition to the basic (scalar) types, sequences of the basic types are
+ supported. The basic types are:
+ </p>
+
+ <ul>
+    <li><strong>string</strong> can hold a human-readable text.
+        <p>Values are represented as <atom>string</atom>.</p>
+        <p>Sequences are represented as <atom dim="[]">string</atom>.</p>
+        <p>'<em>human-readable</em>' here excludes non-printing characters
+        except for CR, LF and TAB [Unicode code points 9,10,13].
+        For binary data use type <strong>binary</strong> instead.</p>
+    </li>
+    <li><strong>boolean</strong> can hold the values <TRUE/> or >FALSE/>.
+        <p>Values are represented as <atom>boolean</atom>.
+        <p>Sequences are represented as <atom dim="[]">boolean</atom>.</p>
+    </li>
+    <li><strong>short</strong> can hold a 16-bit signed integer.
+        <p>Values are represented as <atom>short</atom>.</p>
+        <p>Sequences are represented as <atom dim="[]">short</atom>.</p>
+    </li>
+    <li><strong>int</strong> can hold a 32-bit signed integer.
+        <p>Values are represented as <atom>long</atom>.</p>
+        <p>Sequences are represented as <atom dim="[]">long</atom>.</p>
+    </li>
+    <li><strong>long</strong> can hold a 64-bit signed integer.
+        <p>Values are represented as <atom>hyper</atom>.</p>
+        <p>Sequences are represented as <atom dim="[]">hyper</atom>.</p>
+    </li>
+    <li><strong>double</strong> can hold a floating point number.
+        <p>Values are represented as <atom>double</atom>.</p>
+        <p>Sequences are represented as <atom dim="[]">double</atom>.</p>
+    </li>
+    <li><strong>binary</strong> can hold a sequence of octets.
+        <p>Values are represented as <atom dim="[]">byte</atom>.</p>
+        <p>Sequences are represented as <atom dim="[][]">byte</atom>.</p>
+    </li>
+ </ul>
+
+ <p>Within templates an additional type <strong>any</strong> can occur. When
+ such a template is used to create a new <type>SetElement</type>, the type
+ of the element is initially reported as <atom>any</atom> (having no value).
+ When the value of such an element is first set, it will assume the type used.
+ </p>
+
+ <p>If the schema marks a value as <em>nullable</em> (which is indicated by
+ attribute <const scope="com::sun::star::beans>PropertyAttribute::MAYBEVOID</const>
+ ), its contents may be <NULL/>.
+ </p>
+
+ <p>The configuration should support explicit access to default values
+ (implementing <type scope="com::sun::star::beans">XPropertyState</type>
+ and  <type scope="com::sun::star::beans">XPropertyWithState</type>).
+ </p>
+
+ @see ConfigurationProvider
+    Root instances of this service can be requested from a
+    <type>ConfigurationProvider</type>
+
+ @see ConfigurationUpdateAccess
+    , which is an extended service that includes facilities for modifying
+    configuration data.
 */
 service ConfigurationAccess
 {
-/** allows initializing a new instance of this service, by providing a path specifying the node wanted.
- <p>Usually this should be done by the <type>ConfigurationProvider</type> providing this object.
-*/
-    interface com::sun::star::lang::XInitialization;
-
-/** allows access to immediate children of this node.
- <p><member scope="com::sun::star::container">XNameAccess::getByName</member>
- returns an Any holding either a value or the same interface for another ConfigurationAccess
- if the child is not a value.
-*/
-    interface com::sun::star::container::XNameAccess;
-
-/** allows access to all descendants of this node
- <p><member scope="com::sun::star::container">XHierarchicalNameAccess::getByHierarchicalName</member>
- returns an Any holding either a value or the same interface for another ConfigurationAccess,
- if the descendant is not a value.
-*/
-    interface com::sun::star::container::XHierarchicalNameAccess;
-
-/** provides access to the parent node of this node .
- <p>May return NULL if this object was not obtained as child of another node.
- <p><i>Setting a different parent is generally not supported.</i>
-*/
-    interface com::sun::star::container::XChild;
-
-/** provides information about the name of this node within its parent.
- <p><i>Renaming a node is not supported.</i>
- <p>This interface is optional on a root node directly obtained from a <type>ConfigurationProvider</type>..
-*/
-    [optional] interface com::sun::star::container::XNamed;
-
-/** provides the complete hierarchical name of this node within the configuration tree.
-*/
-    interface com::sun::star::container::XHierarchicalName;
-
-/** allows attaching listeners to this node to monitor changes to child nodes.
-*/
-    interface com::sun::star::container::XContainer;
-
-/** allows attaching listeners to this node to monitor changes to descendant nodes.
- Multiple changes belonging to one single transaction will be notified in a single event.
- This is the recommended event interface for configuration clients.
-*/
-    interface com::sun::star::util::XChangesNotifier;
-
-/** allows accessing configuration items that may have different values for different nodes.
-*/
-    interface com::sun::star::lang::XLocalizable;
-
-/** provides support for inexact names for use in
- <type scope="com::sun::star::container">XNameAccess</type>
- <type scope="com::sun::star::container">XHierarchicalNameAccess</type>
- <type scope="com::sun::star::beans">XPropertySet</type>, etc.
-*/
-    interface com::sun::star::beans::XExactName;
-
-/** provides access to the descendants of this node as properties.
- This interface allows to attach property change listeners to this node.
- Setting property values is not supported on a read-only Configuration access.
- Providing a <type scope="com::sun::star::beans">XPropertySetInfo</type> need not
- be supported on a read-only Configuration access.
- <p><i>This interface is optional in this service</i>
-*/
-    [optional] interface com::sun::star::beans::XPropertySet;
-
-/** provides access to the descendants of this node as properties.
- This interface allows accessing multiple values at once.
- Setting property values is not supported on a read-only Configuration access.
- Providing a <type scope="com::sun::star::beans">XPropertySetInfo</type> need not
- be supported on a read-only Configuration access.
- <p><i>This interface is optional in this service</i>
-*/
-    [optional] interface com::sun::star::beans::XMultiPropertySet;
-
-/** provides access to state of descendants of this node.
- This interface allows accessing default values and determining whether a default is active for a value.
- Setting property values is not supported by a read-only Configuration access.
- <p><i>This interface is optional in this service</i>
-*/
-    [optional] interface com::sun::star::beans::XPropertyState;
-
-
-/** provides access to the descendants of this node as properties.
- This interface allows accessing multiple values and their state at once.
- Setting property values is not supported by a read-only Configuration access.
- <p><i>This interface is optional in this service</i>
-*/
-    [optional] interface com::sun::star::beans::XPropertyAccess;
-
+    /** provides interfaces to access child and descendent elements.
+
+     <p>An implementation actually implements a specialization of this service,
+     which depends on its <em>Container</em> role.
+     </p>
+
+     <p>Implementations shall implement exactly one of:</p>
+     <ul>
+        <li><type>SetAccess</type> if this element is a <em>Set</em>.<li>
+        <li><type>GroupAccess</type> if this element is a <em>Group</em>.<li>
+     </ul>
+    */
+    service HierarchyAccess;
+
+    /** provides interfaces to obtain information about this element and its
+     role and context in the hierarchy
+
+     <p>An implementation actually implements a specialization of this service,
+     which depends on its <em>Element</em> role.
+     </p>
+
+     <p>Implementations shall implement exactly one of:</p>
+     <ul>
+        <li><type>AccessRootElement</type> if this element is the
+            <em>Root</em> of the whole hierarchy. Objects that can be
+            created directly by a <type>ConfigurationProvider</type>
+            implement this service.<li>
+        <li><type>SetElement</type> if this element may be contained in a
+            <em>Set</em>.<li>
+        <li><type>GroupElement</type> if this element is child of a
+            <em>Group</em>.<li>
+     </ul>
+    */
+    service HierarchyElement;
+
+    /** specializes <type>HierarchyAccess</type>,
+     if this element is a <em>Set</em>.
+     <BR/>[Alternatively to <type>GroupAccess</type>]
+    */
+    [optional] service SetAccess;
+
+    /** specializes <type>HierarchyAccess</type>,
+     if this element is a <em>Group</em>.
+     <BR/>[Alternatively to <type>SetAccess</type>]
+    */
+    [optional] service GroupAccess;
+
+    /** specializes <type>HierarchyElement</type>,
+     if this element is the <em>Root</em> of the whole hierarchy.
+     <BR/>[Alternatively to <type>SetElement</type>
+     or <type>GroupElement</type>]
+
+     @see ConfigurationProvider
+        Instances obtained from a <type>ConfigurationProvider</type> will
+        implement this version of <type>HierarchyElement</type>.
+    */
+    [optional] service AccessRootElement;
+
+    /** specializes <type>HierarchyElement</type>,
+     if this element may be contained in a <em>Set</em>.
+     <BR/>[Alternatively to <type>AccessRootElement</type>
+     or <type>GroupElement</type>]
+    */
+    [optional] service SetElement;
+
+    /** specializes <type>HierarchyElement</type>,
+     if this element is child of a <em>Group</em>.
+     <BR/>[Alternatively to <type>AccessRootElement</type>
+     or <type>SetElement</type>]
+    */
+    [optional] service GroupElement;
 };
 
 //=============================================================================
diff --git a/offapi/com/sun/star/configuration/ConfigurationProvider.idl b/offapi/com/sun/star/configuration/ConfigurationProvider.idl
index 4020727af3e6..9d5feeb67204 100644
--- a/offapi/com/sun/star/configuration/ConfigurationProvider.idl
+++ b/offapi/com/sun/star/configuration/ConfigurationProvider.idl
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: ConfigurationProvider.idl,v $
  *
- *  $Revision: 1.4 $
+ *  $Revision: 1.5 $
  *
- *  last change: $Author: mi $ $Date: 2000-12-19 16:03:24 $
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -65,29 +65,194 @@
 #include <com/sun/star/lang/XMultiServiceFactory.idl>
 #endif
 
+#ifndef __com_sun_star_lang_XComponent_idl__
+#include <com/sun/star/lang/XComponent.idl>
+#endif
+
 //=============================================================================
 
 module com { module sun { module star { module configuration {
 
 //=============================================================================
-/** is a one instance service serving as entry point to the configuration.
- Only entire subtrees matching the structure prescribed for elements of this node
- can be added (or removed).
-
-    @guarantees:<B>
+/** manages one (or more) complete set(s) of configuration data and serves as a
+ factory for objects that provide access to a subset of the configuration.
 
-    @author Joerg Barfurth
-    @version 1.0 2000/06/01
+ <p>An implementation is usually obtained from a (global)
+ <type scope="com::sun::star::lang">ServiceManager</type>. The default
+ <code>"com.sun.star.configuration.ConfigurationProvider"</code> object, that is
+ instantiated without using no extra arguments, is a one instance service.
+ </p>
 */
 service ConfigurationProvider
 {
-/** allows creating access objects for specific subtrees.
- The <param>aServiceSpecifier</param> passed to <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member>
- and the arguments to be passed to <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
- will be specified shortly.
+/** allows creating access objects for specific views (aka subsets,fragments)
+ of the configuration.
+.
+ <p>The parameter <var>aServiceSpecifier</var> passed to
+ <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
+ supports at least the service specifiers
+ <code>"com.sun.star.configuration.ConfigurationAccess"</code> and
+ <code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>.
+ </p>
+
+ <p>Using the first of these requests a read-only view of the configuration.
+ The object that is created implements service <type>ConfigurationAccess</type>.
+ To reflect its <em>element role</em> as root of the view, it implements
+ service <type>AccessRootElement</type>.
+ </p>
+
+ <p>Using the second form requests an updatable view of the configuration.
+ The object that is created should implement service
+ <type>ConfigurationUpdateAccess</type>. To reflect its <em>element role</em>
+ which here includes controlling updates for the whole view, it implements
+ service <type>UpdateRootElement</type>.
+ <BR/>If the root element of the view is marked read-only (as indicated
+ by <const scope="com::sun::star::beans">PropertyAttributes::READONLY</const>),
+ the implementation may either raise an exception or return a (read-only)
+ <type>ConfigurationAccess</type>/<type>AccessRootElement</type> instead.
+ </p>
+
+ <p>The arguments passed to
+ <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
+ in parameter <var>aArguments</var> specify the view of the configuration that
+ should be created. That is, they determine the subset of elements that can be
+ accessed starting from the returned object. Each element of the argument
+ sequence should be a <type scope="com::sun::star::beans">PropertyValue</type>,
+ so that the parameters can be identified by name (rather than by position).
+ </p>
+
+ <p>What combinations of arguments are supported depends on the service name.
+ </p>
+
+ <p>With both of the standard service-specifiers above, an implementation must
+ accept a single argument named <code>nodepath</code> of type <atom>string</atom>.
+ This argument must contain the (absolute) path to an element of the
+ configuration. The view that is selected consists of the named element and
+ all its decendants.
+ </p>
+
+ <p>Other arguments can be used to control the behavior of the view. These
+ are different for different implementations. Whether and how they are used
+ may also depend on the configuration store and configuration that were
+ selected when the provider was created.
+ </p>
+
+ <p>An implementation must ignore unknown arguments.</p>
+
+ <p>Some parameters that are commonly supported are:</p>
+
+ <ul>
+    <li>
+       <strong>Selecting data into a view:</strong>
+       <dl>
+         <dd><code>"nodepath"</code> : <atom>string</atom></dd>
+         <dt>specifies the location of the view root in the configuration.</dt>
+         <dd><code>"depth"</code> : <atom>short</atom></dd>
+         <dt>specifies that elements of the hierarchy that are more than the given
+          number of nesting levels away from the root need not be included in the
+          view.
+         </dt>
+         <dd><code>"locale"</code> : <type scope="com::sun::star::lang">Locale</type></dd>
+         <dt>specifies the locale for which localized values should be
+          retrieved.
+         </dt>
+       </dl>
+       <p><strong>Example:<strong> In the hierarchy
+<BR/><pre>
+ A - B1 - C1
+   |
+   - B2 - C2 (localized: de, en, fr, ..)
+   |    |
+   |    - C3 - D1
+   |    |    |
+   |    |    - D2 - E1
+   |    |
+   |    - C4 - D3 - E2 - F1
+   |    |              |
+   |    |              - F2
+   |    |
+   |    - C5
+   |
+   - B3
+   |
+   - B4 - C6 - D4 - E3
+
+</pre>
+         <BR/>selecting a view with <code>nodepath = "/A/B2"</code>,
+         <code>depth = 2</code> and <code>locale = &lt;Locale for en_US&gt;</code>
+         would result in the tree fragment
+<BR/><pre>
+(A-) B2 - C2 (en)
+        |
+        - C3 - D1
+        |    |
+        |    - D2 (..)
+        |
+        - C4 - D3 (..)
+        |
+        - C5
+
+</pre>
+       </p>
+    </li>
+
+    <li>
+       <strong>Controlling cache behavior:</strong> (with providers that
+        cache configuration data)
+       <dl>
+         <dd><code>"lazywrite"</code> : <atom>boolean</atom></dd>
+         <dt>controls how updates are handled in the cache. If <TRUE/>, the
+          cache may operate in <em>write-back</em> mode, where updates at
+          first only affect the cache and are written to persistent storage
+          at some later time. If <FALSE/>, the cache must operate in
+          <em>write-through</em> mode, where updates are written to persistent
+          storage at once - that is before
+          <member scope="com::sun::star::util>XChangesBatch::commitChanges</member>
+          returns.
+         </dt>
+
+         <dd><code>"nocache"</code> : <atom>boolean</atom></dd>
+         <dt>specifies that data for the view is not taken from the cache, but
+          read directly from storage. This may entail that future changes that
+          become visible in the cache are not reflected in this view and that
+          changes done through this view are not reflected in the cache.
+          <BR/><strong>Use with caution !</strong>
+         </dt>
+       </dl>
+    </li>
+ </ul>
+
+ <p><member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member>
+ may be unusable. Only if an implementation supports service names that can be
+ used with no further arguments, it should support this method, returning the
+ same result as if
+ <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
+ had been called using an empty sequence of arguments.
+ </p>
+
 */
     interface com::sun::star::lang::XMultiServiceFactory;
 
+
+/** allows controlling or observing the lifetime of the configuration.
+
+ <p>The owner of the provider may dispose this object
+ (using <member scope="com::sun::star::lang">XComponent::dispose</member>).
+ Note that the default provider is owned by the
+ <type scope="com::sun::star::lang">ServiceManager</type> and should not be
+ disposed by user code.
+ </p>
+
+ <p>Views created by the provider generally refer to data that is managed by
+  the provider. Therefore disposing the provider will cause all objects
+  belonging to these views to be disposed as well. This does not apply to
+  <em>snapshot</em> views that have their own copy of the data - if they are
+  available.
+ </p>
+
+*/
+    interface com::sun::star::lang::XComponent;
+
 };
 
 //=============================================================================
diff --git a/offapi/com/sun/star/configuration/ConfigurationUpdateAccess.idl b/offapi/com/sun/star/configuration/ConfigurationUpdateAccess.idl
index 2411a988adac..c952693f0736 100644
--- a/offapi/com/sun/star/configuration/ConfigurationUpdateAccess.idl
+++ b/offapi/com/sun/star/configuration/ConfigurationUpdateAccess.idl
@@ -2,9 +2,13 @@
  *
  *  $RCSfile: ConfigurationUpdateAccess.idl,v $
  *
- *  $Revision: 1.4 $
+ *  $Revision: 1.5 $
  *
- *  last change: $Author: mi $ $Date: 2001-01-23 10:08:05 $
+<<<<<<< ConfigurationUpdateAccess.idl
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+=======
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+>>>>>>> 1.4
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -65,49 +69,110 @@
 #include <com/sun/star/configuration/ConfigurationAccess.idl>
 #endif
 
-#ifndef __com_sun_star_container_XNameReplace_idl__
-#include <com/sun/star/container/XNameReplace.idl>
+#ifndef __com_sun_star_configuration_SetUpdate_idl__
+#include <com/sun/star/configuration/SetUpdate.idl>
 #endif
 
-#ifndef __com_sun_star_util_XChangesBatch_idl__
-#include <com/sun/star/util/XChangesBatch.idl>
+#ifndef __com_sun_star_configuration_GroupUpdate_idl__
+#include <com/sun/star/configuration/GroupUpdate.idl>
 #endif
 
+#ifndef __com_sun_star_configuration_UpdateRootElement_idl__
+#include <com/sun/star/configuration/UpdateRootElement.idl>
+#endif
 
 //=============================================================================
 
 module com { module sun { module star { module configuration {
 
 //=============================================================================
-/** provides write access to a subtree of the configuration hierarchy.
- Changes to values in the subtree will not become effective unless they are committed using
- <member>XChangesBatch::commitChanges()</member>..
+/** provides modifying access to a fragment of the configuration hierarchy.
+
+ <p>Extends <type>ConfigurationAccess</type> to support modifying values
+ or inserting and removing elements.
+ </p>
 
-    @guarantees:<B>
-    -thread safe
+ <p>Descendants of this service also implement this service
+ (and so on recursively), unless they are marked <em>read-only</em> in the
+ schema (which is indicated by attribute
+ <const scope="com::sun::star::beans>PropertyAttribute::READONLY</const>),
+ in which case they only need implement <type>ConfigurationAccess</type>.
+ </p>
 
-    @author Joerg Barfurth
-    @version 1.0 2000/06/01
+ <p>The classification of implementations that is described for
+ <type>ConfigurationAccess</type> applies to implementations of this service
+ as well. Therefore an implementation will support one of several alternate
+ services describing its <em>Container</em> role and one of several alternate
+ services describing its <em>Element</em> role. These services are
+ extensions of the respective services documented for <type>ConfigurationAccess</type>.
+ </p>
+ <ul>
+    <li><em>Container</em> role:
+        A <em>group</em> permits changing child values.
+        A <em>set</em> permits inserting and removing contained elements.
+    </li>
+    <li><em>Element</em> role:
+        The root element of a modifiable tree provides extended functionality
+        to control processing of changes for the entire tree (fragment) by
+        supporting <type scope="com::sun::star::util>XChangesBatch</type>.
+        For elements of a <em>set</em> or a <em>group</em> no additinal
+        interfaces are supported.
+    </li>
+ </ul>
+
+ @see ConfigurationProvider
+    Root instances of this service can be requested from a
+    <type>ConfigurationProvider</type>
 */
 service ConfigurationUpdateAccess
 {
-/** is extended by this service to allow write access.
- The property set interfaces that were optional in the base service are
- mandatory in this service.
-*/
+    /** is the basic service providing (read) access to an element of the
+     configuration hierarchy and its child and descendent elements.
+
+     <p>The <type>HierarchyAccess</type> specialization implemented will be
+     further specialized to support modifying access.
+     Implementations shall therefore implement one of <type>SetUpdate</type> or
+     <type>GroupUpdate</type> depending on the <em>Container</em> role.
+     </p>
+
+     <p>If the <type>HierarchyElement</type> specialization that is implemented
+     is <type>AccessRootElement</type>, the implementation must support the
+     extended functionality of <type>UpdateRootElement</type>. Otherwise there
+     are no new requirements mandated by the <em>Element</em> role.
+     </p>
+
+    */
     service ConfigurationAccess;
 
-/** allows changing child values of this node.
-*/
-    interface com::sun::star::container::XNameReplace;
+    /** specializes <type>SetAccess</type> to support modifying the element.
 
-/** allows committing changes done on this node or nodes obtained from it.
- This interface is optional and will be present if, and only if, this is the
- root node of the update (as initially obtained from a <type>ConfigurationProvider</type>).
- Otherwise <member>XChild::getParent()</member> can be used to navigate to the root
- of the update to commit any changes.
-*/
-    [optional] interface com::sun::star::util::XChangesBatch;
+     <p>Implemented, if this element is a <em>Set</em>.
+     <BR/>[Alternatively to <type>GroupUpdate</type>]
+     </p>
+    */
+    [optional] service SetUpdate;
+
+    /** specializes <type>GroupAccess</type> to support modifying contained
+     data.
+
+     <p>Implemented, if this element is a <em>Group</em>.
+     <BR/>[Alternatively to <type>SetUpdate</type>]
+     </p>
+    */
+    [optional] service GroupUpdate;
+
+    /** specializes <type>AccessRootElement</type>, to support transaction-like
+     control over a batch of changes accumulated within the tree (fragment).
+
+     <p>Implemented, if this element is the <em>Root</em> of the whole hierarchy.
+     <BR/>[Alternatively to <type>SetElement</type> or <type>GroupElement</type>]
+     </p>
+
+     @see ConfigurationProvider
+        Instances obtained from a <type>ConfigurationProvider</type> will
+        implement this version of <type>HierarchyElement</type>.
+    */
+    [optional] service UpdateRootElement;
 };
 
 //=============================================================================
diff --git a/offapi/com/sun/star/configuration/GroupAccess.idl b/offapi/com/sun/star/configuration/GroupAccess.idl
new file mode 100644
index 000000000000..c3431ad010b5
--- /dev/null
+++ b/offapi/com/sun/star/configuration/GroupAccess.idl
@@ -0,0 +1,195 @@
+/*************************************************************************
+ *
+ *  $RCSfile: GroupAccess.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_GroupAccess_idl__
+#define __com_sun_star_configuration_GroupAccess_idl__
+
+#ifndef __com_sun_star_configuration_HierarchyAccess_idl__
+#include <com/sun/star/configuration/HierarchyAccess.idl>
+#endif
+
+#ifndef __com_sun_star_configuration_PropertyHierarchy_idl__
+#include <com/sun/star/configuration/PropertyHierarchy.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XPropertyState_idl__
+#include <com/sun/star/beans/XPropertyState.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XMultiPropertyState_idl__
+#include <com/sun/star/beans/XMultiPropertyState.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides access to a predefined heterogeneous group of values and nested
+ trees as part of a (by name) hierarchy.
+
+ <p>Provides access to and information about its children and descendants
+ viewed either as properties or as contained elements.
+ </p>
+
+ <p><em>Groups</em> are static collections within the hierarchy.</p>
+
+ <p>The number and names of contained elements are fixed in advance,
+ and each child may have a different type.
+ </p>
+
+ <p>This service subsumes two alternate ways of accessing child and descendent
+ elements. These strongly overlap, supporting the basic identity
+ <code>xGroup.getPropertyValue( aName ) == xGroup.getByName( aName )</code>.
+ </p>
+
+ @see com::sun::star::configuration::GroupElement
+    Child objects of this service generally implement service GroupElement.
+
+ @see com::sun::star::configuration::SetAccess
+    A complementary service, providing for dynamic homogeneous sets of elements.
+
+*/
+service GroupAccess
+{
+/** is the basic service for accessing child and descendent nodes using
+ a view of the tree as a container of values and structuring elements.
+*/
+    service HierarchyAccess;
+
+/** is the basic service for accessing child and descendent nodes using
+ a view of the tree as a hierarchy of properties and subproperties.
+
+ <p>This view is meaningful only for a static fragment of the hierarchy
+ ( objects' properties may change, but not which properties they have ).
+ Therefore dynamic elements of the hierarchy (see <type>SetAccess</type>)
+ do not implement service <type>PropertyHierarchy</type>.
+ </p>
+
+ <p>If such elements occur as (sub)properties of an implementation,
+ it is not specified whether direct subproperty access using
+ <type scope="com::sun::star::beans">XHierarchicalPropertySet</type> or
+ <type scope="com::sun::star::beans">XMultiHierarchicalPropertySet</type> can
+ be used to access descendants of such such elements.
+ </p>
+
+ <p>Similarly, information about such descendants may not be available from
+ the <type scope="com::sun::star::beans">XHierarchicalPropertySetInfo</type>
+ the implementation provides.
+ </p>
+
+ <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
+ all properties and subproperties will be reported as having attribute
+ <const scope="com::sun::star::beans">PropertyAttribute::READONLY</const> set,
+ and attempts to change property values will fail.
+ </p>
+*/
+    service PropertyHierarchy;
+
+/** provides access to the state of child elements of an implementation. [optional]
+
+ <p>This interface may be missing if the hierarchy (or a hierarchy fragment
+ that contains this implementation as element) does not support default values.
+ </p>
+
+ <p>If elements that are not simple values, but objects themselves, support
+ a default state (as indicated by
+ <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
+ they should implement
+ <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
+ the <type scope="com::sun::star::beans">PropertyState</type> applies to all
+ their children and recursively to all descendants.
+ </p>
+
+ <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
+ attempts to change property states will fail.
+ </p>
+*/
+    [optional] interface com::sun::star::beans::XPropertyState;
+
+/** provides access to the states of multiple child elements of
+ an implementation. [optional]
+
+ <p>This interface may be missing if the hierarchy (or a hierarchy fragment
+ that contains this implementation as element) does not support default values,
+ or if the implementation does not support recursive defaults (see below).
+ </p>
+
+ <p>If elements that are not simple values, but objects themselves, support
+ a default state (as indicated by
+ <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
+ they should implement
+ <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
+ the <type scope="com::sun::star::beans">PropertyState</type> applies to all
+ their children and recursively to all descendants.
+ </p>
+
+ <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
+ attempts to change property states will fail.
+ </p>
+*/
+    [optional] interface com::sun::star::beans::XMultiPropertyState;
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/GroupElement.idl b/offapi/com/sun/star/configuration/GroupElement.idl
new file mode 100644
index 000000000000..250241aad847
--- /dev/null
+++ b/offapi/com/sun/star/configuration/GroupElement.idl
@@ -0,0 +1,122 @@
+/*************************************************************************
+ *
+ *  $RCSfile: GroupElement.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_GroupElement_idl__
+#define __com_sun_star_configuration_GroupElement_idl__
+
+#ifndef __com_sun_star_configuration_HierarchyElement_idl__
+#include <com/sun/star/configuration/HierarchyElement.idl>
+#endif
+
+#ifndef __com_sun_star_container_XChild_idl__
+#include <com/sun/star/container/XChild.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides information about a predefined element contained in a
+ heterogeneous group of elements within a (by name) hierarchy.
+
+ <p>Provides information about the element.
+ Provides access to its containing 'group' object.
+ </p>
+
+ <p>A group element bears a predefined name. It may only exist within a
+ containing 'group' object.
+ </p>
+
+ @see com::sun::star::configuration::GroupAccess
+    Parent objects of this service generally implement service GroupAccess.
+
+ @see com::sun::star::configuration::SetElement
+    A complementary service, for elements of a dynamic homogeneous container.
+
+ @see com::sun::star::configuration::AccessRootElement
+    A complementary service, for the root element of a hierarchy.
+
+*/
+service GroupElement
+{
+/** is the basic service for accessing information about an element in the
+ hierarchy.
+*/
+    service HierarchyElement;
+
+/** provides access to the containing 'group' object.
+
+ <p>In this service this interface is mandatory</p>
+
+ <p><member scope="com::sun::star::container">XChild::getParent</member>
+ shall not return NULL.
+ </p>
+
+ <p><em>Setting a different parent is not supported.</em></p>
+*/
+    interface com::sun::star::container::XChild;
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/GroupUpdate.idl b/offapi/com/sun/star/configuration/GroupUpdate.idl
new file mode 100644
index 000000000000..9a5e64431012
--- /dev/null
+++ b/offapi/com/sun/star/configuration/GroupUpdate.idl
@@ -0,0 +1,129 @@
+/*************************************************************************
+ *
+ *  $RCSfile: GroupUpdate.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_GroupUpdate_idl__
+#define __com_sun_star_configuration_GroupUpdate_idl__
+
+#ifndef __com_sun_star_configuration_GroupAccess_idl__
+#include <com/sun/star/configuration/GroupAccess.idl>
+#endif
+
+#ifndef __com_sun_star_container_XNameReplace_idl__
+#include <com/sun/star/container/XNameReplace.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides write access to a predefined heterogeneous group of values
+ and nested trees as part of a (by name) hierarchy.
+
+ <p>Allows replacing values with new values.
+ </p>
+
+ <p>This service extends <type>GroupAccess</type> to support
+ modifying values.
+ </p>
+*/
+service GroupUpdate
+{
+/** is the basic service providing (read) access to a 'group' element of the
+ hierarchy.
+
+ <p>Any hild and descendant objects shall again support modifying access,
+ unless they represent a read-only tree element (as indicated by
+ <const scope="com::sun::star::beans">PropertyAttribute::READONLY</const>).
+ </p>
+*/
+    service GroupAccess;
+
+/** allows replacing values.
+
+ <p>This service extends the interface
+ <type scope="com::sun::star::container">XNameAccess</type> supported
+ by service <type>GroupAccess</type> to allow changing values.
+ This strongly overlaps with functionality available through
+ <type>PropertyHierarchy</type> (from <type>GroupAccess</type>), so that
+ <code>xGroup.setPropertyValue( aName, aValue )</code> is equivalent to
+ <code>xGroup.replaceByName( aName, aValue )</code>.
+ </p>
+
+ <p>Changes can be observed by registering a listener with interface
+ <type scope="com::sun::star::beans">XPropertySet</type> or
+ <type scope="com::sun::star::beans">XMultiPropertySet</type>.
+ </p>
+
+ <p>Elements of this group may be replaced only if they are of simple type
+ (the type returned by
+ <member scope="com::sun::star::container">XElementAccess::getElementType</member>
+ is not an interface type). Replacing whole subtrees is not supported.
+ </p>
+*/
+    interface com::sun::star::container::XNameReplace;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/HierarchyAccess.idl b/offapi/com/sun/star/configuration/HierarchyAccess.idl
new file mode 100644
index 000000000000..100299447b59
--- /dev/null
+++ b/offapi/com/sun/star/configuration/HierarchyAccess.idl
@@ -0,0 +1,142 @@
+/*************************************************************************
+ *
+ *  $RCSfile: HierarchyAccess.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_HierarchyAccess_idl__
+#define __com_sun_star_configuration_HierarchyAccess_idl__
+
+#ifndef __com_sun_star_container_XNameAccess_idl__
+#include <com/sun/star/container/XNameAccess.idl>
+#endif
+
+#ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__
+#include <com/sun/star/container/XHierarchicalNameAccess.idl>
+#endif
+
+#ifndef __com_sun_star_container_XContainer_idl__
+#include <com/sun/star/container/XContainer.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XExactName_idl__
+#include <com/sun/star/beans/XExactName.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides access to a (by name) hierarchy of descendant elements.
+
+ <p>Values that are direct or indirect descendants of this tree node can be
+ retrieved, non-value subnodes can be navigated using container interfaces.
+ Other interfaces provide access to information about this node.
+ Changes to values in the subtree can be monitored by event listeners.
+ </p>
+
+ <p>Elements of this (by name) container that are not simple values
+ are similar containers themselves, thus (recursively) forming a
+ hierarchical tree.
+ </p>
+
+ <p>Implementations of this service usually also implement
+ service <type>HierarchyElement</type>, which concerns the complementary role
+ of being accessible as an element of the Hierarchy.
+ </p>
+
+*/
+service HierarchyAccess
+{
+/** allows access to immediate children of this node.
+
+ <p><member scope="com::sun::star::container">XNameAccess::getByName</member>
+ returns an Any holding either a simple value or an interface
+ on another HierarchyAccess if the child is not a simple value.
+ </p>
+*/
+    interface com::sun::star::container::XNameAccess;
+
+/** allows access to all descendants of this node
+
+ <p><member scope="com::sun::star::container">XHierarchicalNameAccess::getByHierarchicalName</member>
+ returns an Any holding either a simple value or an interface
+ on another HierarchyAccess if the descendant is not a simple value.
+ </p>
+*/
+    interface com::sun::star::container::XHierarchicalNameAccess;
+
+/** allows attaching listeners to this node to monitor changes to immediate child nodes.
+*/
+    interface com::sun::star::container::XContainer;
+
+/** provides support for inexact names.
+ <p>Exact names can be obtained for simple or hierarchical names for use in
+ <type scope="com::sun::star::container">XNameAccess</type>,
+ <type scope="com::sun::star::container">XHierarchicalNameAccess</type>,
+ <type scope="com::sun::star::beans">XPropertySet</type>, etc.
+ </p>
+*/
+    interface com::sun::star::beans::XExactName;
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/HierarchyElement.idl b/offapi/com/sun/star/configuration/HierarchyElement.idl
new file mode 100644
index 000000000000..46d814b8d8ec
--- /dev/null
+++ b/offapi/com/sun/star/configuration/HierarchyElement.idl
@@ -0,0 +1,167 @@
+/*************************************************************************
+ *
+ *  $RCSfile: HierarchyElement.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_HierarchyElement_idl__
+#define __com_sun_star_configuration_HierarchyElement_idl__
+
+#ifndef __com_sun_star_container_XNamed_idl__
+#include <com/sun/star/container/XNamed.idl>
+#endif
+
+#ifndef __com_sun_star_container_XHierarchicalName_idl__
+#include <com/sun/star/container/XHierarchicalName.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XProperty_idl__
+#include <com/sun/star/beans/XProperty.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XPropertyWithState_idl__
+#include <com/sun/star/beans/XPropertyWithState.idl>
+#endif
+
+#ifndef __com_sun_star_container_XChild_idl__
+#include <com/sun/star/container/XChild.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides information about an element within a (by name) hierarchy.
+
+ <p>The local name and the full hierarchical name can be retrieved.
+ Attributes detailing the role of the element can be queried.
+ The state of the element (regarding defaults) can be accessed.
+ </p>
+
+ <p>Implementations of this service usually also implement
+ service <type>HierarchyAccess</type>, which concerns the complementary role
+ of providing access to subelements of the Hierarchy.
+ </p>
+*/
+service HierarchyElement
+{
+/** provides the complete hierarchical name of this element
+ within the hierarchy tree.
+*/
+    interface com::sun::star::container::XHierarchicalName;
+
+/** provides the (local) name of this element within its parent.
+
+ <p><em>Renaming an element is generally not supported.</em></p>
+*/
+    interface com::sun::star::container::XNamed;
+
+/** provides a property descriptor for this element.[optional]
+
+ <p>This interface may be missing, if the hierarchy supports no traits that are
+ described by <type.scope="com::sun::star::beans">PropertyAttribute</type>
+ values.
+ </p>
+
+ <p>If the parent of this object implements
+ <type scope="com::sun::star::beans">XPropertySetInfo</type> then this returns
+ the same <type scope="com::sun::star::beans">Property</type> as the
+ <type scope="com::sun::star::beans">XPropertySetInfo</type> of the parent.
+ </p>
+*/
+    [optional] interface com::sun::star::beans::XProperty;
+
+/** provides access to the (default) state of this element. [optional]
+
+ <p>This interface may be missing, if the hierarchy supports access to
+ a default state and values only for simple values (or not at all)
+ </p>
+
+ <p>If the parent of this object implements
+ <type scope="com::sun::star::beans">XPropertyState</type> then members
+ of this interface have the same effect as corresponding members of the parent.
+ </p>
+
+ <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
+ attempts to change property states will fail.
+ </p>
+*/
+    [optional] interface com::sun::star::beans::XPropertyWithState;
+
+/** provides access to the parent of this element [optional].
+
+ <p>This interface may be missing, if this object is not obtained
+ as child or descendant of another tree node
+ (e.g. directly from a factory or provider).
+ </p>
+
+ <p><member scope="com::sun::star::container">XChild::getParent</member>
+ returns NULL, if this object is (currently) not contained in another node.
+ </p>
+
+ <p><em>Setting a different parent is generally not supported.</em></p>
+*/
+    [optional] interface com::sun::star::container::XChild;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/PropertyHierarchy.idl b/offapi/com/sun/star/configuration/PropertyHierarchy.idl
new file mode 100644
index 000000000000..998c41e078c4
--- /dev/null
+++ b/offapi/com/sun/star/configuration/PropertyHierarchy.idl
@@ -0,0 +1,139 @@
+/*************************************************************************
+ *
+ *  $RCSfile: PropertyHierarchy.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_PropertyHierarchy_idl__
+#define __com_sun_star_configuration_PropertyHierarchy_idl__
+
+#ifndef __com_sun_star_beans_XPropertySet_idl__
+#include <com/sun/star/beans/XPropertySet.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XMultiPropertySet_idl__
+#include <com/sun/star/beans/XMultiPropertySet.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XHierarchicalPropertySet_idl__
+#include <com/sun/star/beans/XHierarchicalPropertySet.idl>
+#endif
+
+#ifndef __com_sun_star_beans_XMultiHierarchicalPropertySet_idl__
+#include <com/sun/star/beans/XMultiHierarchicalPropertySet.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides access to and information about properties and subproperties
+ of an implementation.
+
+ <p>Properties in a property set may be full-fledged objects that have
+ properties themselves (and so on recursively), thereby forming a hierarchy
+ of properties. This service describes such a hierarchy, and allows
+ direct access even to subproperties.
+ </p>
+
+ <p>Properties of an implementation that are objects themselves will often
+ implement <type scope="com::sun::star::beans">XProperty</type> to allow
+ direct access to information about the object.
+ If such properties have properties of their own, they should fully implement
+ <type>PropertyHierarchy</type> (this service) again.
+ </p>
+*/
+service PropertyHierarchy
+{
+/** provides access to and information about the (immediate) properties
+ of an implementation.
+*/
+    interface com::sun::star::beans::XPropertySet;
+
+/** provides access to and information about the (immediate) properties
+ of an implementation.
+
+ <p>This interface allows retrieving or setting multiple properties at once.
+ Accesses are guaranteed to occur as single atomic operations even if
+ multiple threads are accessing the object simultaneously.
+ </p>
+*/
+    interface com::sun::star::beans::XMultiPropertySet;
+
+/** provides access to and information about the whole hierarchy
+ of properties and subproperties of an implementation.
+*/
+    interface com::sun::star::beans::XHierarchicalPropertySet;
+
+/** provides access to and information about the whole hierarchy
+ of properties and subproperties of an implementation.
+
+ <p>This interface allows retrieving or setting multiple properties at once.
+ Accesses are guaranteed to occur as single atomic operations even if
+ multiple threads are accessing the object simultaneously.
+ </p>
+*/
+    interface com::sun::star::beans::XMultiHierarchicalPropertySet;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/SetAccess.idl b/offapi/com/sun/star/configuration/SetAccess.idl
new file mode 100644
index 000000000000..982cf1828423
--- /dev/null
+++ b/offapi/com/sun/star/configuration/SetAccess.idl
@@ -0,0 +1,147 @@
+/*************************************************************************
+ *
+ *  $RCSfile: SetAccess.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_SetAccess_idl__
+#define __com_sun_star_configuration_SetAccess_idl__
+
+#ifndef __com_sun_star_configuration_HierarchyAccess_idl__
+#include <com/sun/star/configuration/HierarchyAccess.idl>
+#endif
+
+#ifndef __com_sun_star_configuration_SimpleSetAccess_idl__
+#include <com/sun/star/configuration/SimpleSetAccess.idl>
+#endif
+
+#ifndef __com_sun_star_container_XContainer_idl__
+#include <com/sun/star/container/XContainer.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides access to a dynamic homogeneous set of values or nested
+ trees within a (by name) hierarchy.
+
+ <p>Also provides information about the template for elements.
+ Allows normalizing externally generated names.
+ </p>
+
+ <p><em>Sets</em> here are dynamic containers within the hierarchy.</p>
+
+ <p>The number and names of contained elements is not fixed in advance,
+ but all elements have to be of one predetermined type.
+ </p>
+
+ @see com::sun::star::configuration::SetElement
+    Child objects of this service generally implement <type>SetElement</type>.
+    The template name returned by the child from
+    <member>XTemplateInstance::getTemplateName</member>
+    corresponds to the name returned by the set from
+    <member>XTemplateContainer::getElementTemplateName</member>.
+
+ @see com::sun::star::configuration::GroupAccess
+    A complementary service, providing for static heterogeneous groups of
+    elements within the hierarchy.
+
+*/
+service SetAccess
+{
+/** is the basic service for accessing child and descendent nodes in a hierarchy.
+
+ <p>External names (from foreign namespaces) should be normalized using
+ <member scope="com::sun::star::util">XStringEscape::escapeString</member>
+ (if available) before using them as element names.
+ </p>
+*/
+    service HierarchyAccess;
+
+/** is the basic service providing information about and access to elements
+ of a (not necessarily hierarchical) <em>set</em>.
+
+ <p>Interface <type scope="com::sun::star::configuration>XTemplateContainer</type>,
+ which is optional in <type>SimpleSetAccess</type> must always be implemented
+ in this service, if the elements are of object type.
+ </p>
+
+ <p>If an implementation handles naming restrictions transparently, it must
+ also handle the case of element names embedded in hierarchical names - passed
+ to any object in the hierarchy. Otherwise the implementation should implement
+ <type scope="com::sun::star::util>XStringEscape</type>, in which case the
+ client is responsible for constructing correct hierarchical names.
+ </p>
+*/
+    service SimpleSetAccess;
+
+/** allows attaching listeners to this node to monitor changes to the set.
+
+ <p>In this service support for notifications is mandatory.
+ </p>
+*/
+    interface com::sun::star::container::XContainer;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/SetElement.idl b/offapi/com/sun/star/configuration/SetElement.idl
new file mode 100644
index 000000000000..a8cc6bcbe5ca
--- /dev/null
+++ b/offapi/com/sun/star/configuration/SetElement.idl
@@ -0,0 +1,220 @@
+/*************************************************************************
+ *
+ *  $RCSfile: SetElement.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_SetElement_idl__
+#define __com_sun_star_configuration_SetElement_idl__
+
+#ifndef __com_sun_star_configuration_HierarchyElement_idl__
+#include <com/sun/star/configuration/HierarchyElement.idl>
+#endif
+
+#ifndef __com_sun_star_container_XChild_idl__
+#include <com/sun/star/container/XChild.idl>
+#endif
+
+#ifndef __com_sun_star_lang_XComponent_idl__
+#include <com/sun/star/lang/XComponent.idl>
+#endif
+
+#ifndef __com_sun_star_configuration_XTemplateInstance_idl__
+#include <com/sun/star/configuration/XTemplateInstance.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides information about a dynamic element that can be inserted into a
+ homogeneous set of elements within a (by name) hierarchy.
+
+ <p>Provides information about the element.
+ Provides access to its containing 'set' object.
+ Allows controlling the lifetime of the element.
+ </p>
+
+ <p>Set elements may be added to and removed from the hierarchy at runtime.
+ They bear user-defined names. They may exist independently, outside any
+ container.
+ </p>
+
+ <p>New set element instances generally are created through members of
+ <type scope="com::sun::star::lang">XSingleServiceFactory</type> or
+ (if supported) <type scope="com::sun::star::lang">XMultiServiceFactory</type>
+ on an implementation of <type>SetUpdate</type>. Initially they are not
+ contained in a 'set' object, and have no (meaningful) name.
+ </p>
+
+ <p>While an instance is not contained in a 'set' object, it is owned by
+ the client and can be disposed by calling
+ <member scope="com::sun::star::lang">XComponent::dispose</member>. The name
+ of the object can freely be changed in that situation (though without
+ persistent effect).
+ </p>
+
+ <p>When the instance is inserted into a set (which includes replacing an
+ existing element), ownership is transferred to the container.
+ While it is contained in the container, clients must not dispose the
+ object. When inserted, the name of the object is fixed and is used to
+ identify it within the container. An implementation should support
+ <member scope="com::sun::star::container">XNamed::setName</member> even in
+ this case. If it does, changing the name has the same effect of removing
+ the object (under the old name) and then reinserting it into the same
+ container (using the new name).
+ </p>
+
+ <p>When an instance is removed from a set (which includes being replaced by
+ a new element), ownership is transferred to the client again. It can then be
+ disposed or reinserted into a container. An instance can only be inserted
+ into a container, if it was obtained from the same hierarchy.
+ </p>
+
+ <p>When a set element is removed from its set from outside the hierarchy, the
+ container disposes the object. This occurrence can be detected by registering
+ a <type scope="com::sun::star::lang">XEventListener</type> with the object.
+ </p>
+
+ <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
+ changing the name or parent is not supported (the object can't be removed from
+ its container anyway).
+ </p>
+
+ @see com::sun::star::configuration::SetAccess
+    Parent objects of this service generally implement service SetAccess.
+
+ @see com::sun::star::configuration::GroupElement
+    A complementary service, for elements of a static heterogeneous collection.
+
+ @see com::sun::star::configuration::AccessRootElement
+    A complementary service, for the root element of a hierarchy.
+
+*/
+service SetElement
+{
+/** is the basic service for accessing information about an element in the
+ hierarchy.
+*/
+    service HierarchyElement;
+
+/** provides access to the containing 'set' object.
+
+ <p>In this service this interface is mandatory</p>
+
+ <p><member scope="com::sun::star::container">XChild::getParent</member>
+ returns <NULL/>, if the object is currently not contained in a container.
+ </p>
+
+ <p>An implementation may also support
+ <member scope="com::sun::star::container">XChild::setParent</member>.
+ If it does, changing the parent has the effect of first removing the object
+ from its old parent (if any) and then inserting it into the new parent
+ (unless that is <NULL/>) under the same name. The new parent must be part of
+ the same hierarchy as the old one. The name of the object must have been set
+ before.
+ </p>
+*/
+    interface com::sun::star::container::XChild;
+
+/** allows controlling or observing the lifetime of the object.
+
+ <p>Clients may dispose the object (using
+ <member scope="com::sun::star::lang">XComponent::dispose</member>, only if
+ the object is currently not contained in a container (
+ <member scope="com::sun::star::container">XChild::getParent</member>
+ returns <NULL/>).
+ </p>
+
+ <p>Clients may register a <type scope="com::sun::star::lang">XEventListener</type>
+ to be notified, if the object is removed from its container by an outside source.
+ </p>
+*/
+    interface com::sun::star::lang::XComponent;
+
+/** provides information about the type of the element.
+
+ <p>Set elements have a predetermined structure (their <em>type</em>),
+ that is described by and can be generated from a <em>Template</em>.
+ </p>
+
+ <p>If the object was created using interface
+ <type scope="com::sun::star::lang">XSingleServiceFactory</type>
+ on an implementation of <type>SetUpdate</type>, this interface describes the
+ same template as interface <type>XTemplateContainer</type> on that
+ <type>SetUpdate</type>.
+ </p>
+ <p>If the object was created using interface
+ <type scope="com::sun::star::lang">XMultiServiceFactory</type>
+ on an implementation of <type>SetUpdate</type>, this interface describes the
+ template whose name was used as a service identifier for the factory method.
+ </p>
+ <p>Otherwise the semantics of the information provided about the template depends on the
+ implementation.
+ </p>
+
+ @ see com::sun::star::configuration::XTemplateContainer
+*/
+    interface com::sun::star::configuration::XTemplateInstance;
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/SetUpdate.idl b/offapi/com/sun/star/configuration/SetUpdate.idl
new file mode 100644
index 000000000000..90244e8a45f8
--- /dev/null
+++ b/offapi/com/sun/star/configuration/SetUpdate.idl
@@ -0,0 +1,139 @@
+/*************************************************************************
+ *
+ *  $RCSfile: SetUpdate.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_SetUpdate_idl__
+#define __com_sun_star_configuration_SetUpdate_idl__
+
+#ifndef __com_sun_star_configuration_SetAccess_idl__
+#include <com/sun/star/configuration/SetAccess.idl>
+#endif
+
+#ifndef __com_sun_star_configuration_SimpleSetUpdate_idl__
+#include <com/sun/star/configuration/SimpleSetUpdate.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides write access to a dynamic homogeneous set of values or nested
+ trees within a (by name) hierarchy.
+
+ <p>Allows adding and removing elements.
+ Helps creating new elements to be added.
+ </p>
+
+ <p>This service extends <type>SetAccess</type> to support
+ modifying the container.
+ </p>
+
+ <p>Any child and descendant objects shall again support modifying access,
+ unless they represent a read-only tree element (as indicated by
+ <const scope="com::sun::star::beans">PropertyAttribute::READONLY</const>).
+ </p>
+*/
+service SetUpdate
+{
+/** is the basic service providing (read) access to a <em>set</em> within the
+ hierarchy.
+*/
+    service SetAccess;
+
+/** is the basic service providing modifying access to a
+ (not necessarily hierarchical) <em>set</em>.
+
+ <p>Changes can be observed by registering a listener with interface
+ <type scope="com::sun::star::container">XContainer</type>.
+ </p>
+
+ <p>If the elements of this set are of object type,new elements are constructed
+ to match the tree structure prescribed by the element template of this set, when
+ using interfaces <type scope="com::sun::star::lang">XSingleServiceFactory</type>
+ and (if supported) <type scope="com::sun::star::lang">XMultiServiceFactory</type>.
+ </p>
+
+ <p>Objects that are removed from a set can be reinserted into any set supporting
+ the same template within the same hierarchy (even under a different name).
+ </p>
+
+ <p>Implementations that support insertion of objects that weren't obtained
+ from within the hierarchy must reject elements that don't have the correct
+ structure as described by the template, even if the object returns the
+ correct template name from <member>XTemplateInstance::getTemplateName</member>.
+ </p>
+
+ <p>Other ways in which an element may be moved among or within compatible sets
+ include <member scope="com::sun::star::container">XChild::setParent</member>
+ and <member scope="com::sun::star::container">XNamed::setName</member>, if
+ the element implements them.
+ </p>
+
+ @see com::sun::star::configuration::SetElement
+*/
+    service SimpleSetUpdate;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/SimpleSetAccess.idl b/offapi/com/sun/star/configuration/SimpleSetAccess.idl
new file mode 100644
index 000000000000..738a19ab4948
--- /dev/null
+++ b/offapi/com/sun/star/configuration/SimpleSetAccess.idl
@@ -0,0 +1,152 @@
+/*************************************************************************
+ *
+ *  $RCSfile: SimpleSetAccess.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_SimpleSetAccess_idl__
+#define __com_sun_star_configuration_SimpleSetAccess_idl__
+
+#ifndef __com_sun_star_container_XNameAccess_idl__
+#include <com/sun/star/container/XNameAccess.idl>
+#endif
+
+#ifndef __com_sun_star_configuration_XTemplateContainer_idl__
+#include <com/sun/star/configuration/XTemplateContainer.idl>
+#endif
+
+#ifndef __com_sun_star_util_XStringEscape_idl__
+#include <com/sun/star/util/XStringEscape.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides access to a dynamic homogeneous (nonhierarchical) set of values
+ or objects.
+
+ <p>Also rovides information about the template for elements.
+ Allows normalizing externally generated names.
+ </p>
+
+ <p><em>Sets</em> are dynamic containers.</p>
+
+ <p>The number and names of contained elements is not fixed in advance,
+ but all elements have to be of one predetermined type.
+ </p>
+*/
+service SimpleSetAccess
+{
+/** is the basic service for accessing child and descendent nodes.
+
+ <p>External names (from foreign namespaces) should be normalized using
+ <member scope="com::sun::star::util">XStringEscape::escapeString</member>
+ (if available) before using them as element names.
+ </p>
+*/
+    interface com::sun::star::container::XNameAccess;
+
+/** provides additional information about the element type. [optional]
+
+ <p>All set elements (if they are not just simple values but whole trees)
+ must have a predetermined structure (their <em>type</em>)
+ that is described by and can be generated from a <em>Template</em>.
+ The semantics of the information provided about the template depends on the
+ implementation.
+ </p>
+
+ <p>This interface may be missing, if the Implementation can support only
+ one predefined type, or if the elements are of a simple type and
+ no further information is available.  In the latter case
+ <member scope="com::sun::star::container">XElementAccess::getElementType()</member>
+ provides all the information there is about the elements' type.
+ </p>
+*/
+    interface com::sun::star::configuration::XTemplateContainer;
+
+/** allows normalizing and denormalizing external names. [optional]
+
+ <p>Elements of a <em>Set</em> often correspond to external entities
+ (e.g.files, web pages, people, ...) whose names obey different rules and
+ restrictions than names that are valid in the hierarchical naming scheme.
+ </p>
+
+ <p>This interface may be missing, if there are no naming restrictions,
+ if the implementation handles any such conversions internally,
+ or if clients must enforce such restrictions themselves. In the last case
+ the naming scheme documentation must fully document any restrictions.
+ </p>
+*/
+    interface com::sun::star::util::XStringEscape;
+
+/** allows attaching listeners to this node to monitor changes to the set. [optional]
+
+ <p>This interface may be missing if the implementation does not support
+ notifications.
+ </p>
+*/
+    interface com::sun::star::container::XContainer;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/SimpleSetUpdate.idl b/offapi/com/sun/star/configuration/SimpleSetUpdate.idl
new file mode 100644
index 000000000000..e008cd166afa
--- /dev/null
+++ b/offapi/com/sun/star/configuration/SimpleSetUpdate.idl
@@ -0,0 +1,213 @@
+/*************************************************************************
+ *
+ *  $RCSfile: SimpleSetUpdate.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_SimpleSetUpdate_idl__
+#define __com_sun_star_configuration_SimpleSetUpdate_idl__
+
+#ifndef __com_sun_star_configuration_SimpleSetAccess_idl__
+#include <com/sun/star/configuration/SimpleSetAccess.idl>
+#endif
+
+#ifndef __com_sun_star_container_XNameContainer_idl__
+#include <com/sun/star/container/XNameContainer.idl>
+#endif
+
+#ifndef __com_sun_star_lang_XSingleServiceFactory_idl__
+#include <com/sun/star/lang/XSingleServiceFactory.idl>
+#endif
+
+#ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
+#include <com/sun/star/lang/XMultiServiceFactory.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides write access to a dynamic homogeneous (non-hierarchical) set of
+ values or objects.
+
+ <p>Allows adding and removing elements.
+ Helps creating new elements to be added.
+ </p>
+
+ <p>This service extends <type>SimpleSetAccess</type> to support
+ modifying the container. Any child objects shall in turn support
+ modifying access.
+ </p>
+*/
+service SimpleSetUpdate
+{
+/** is the basic service providing (read) access to a (not necessarily
+ hierarchical) <em>set</em>.
+*/
+    service SimpleSetAccess;
+
+/** allows inserting, removing and replacing elements.
+
+ <p>This interface extends the interface
+ <type scope="com::sun::star::container">XNameAccess</type> supported
+ by service <type>SimpleSetAccess</type> to allow modifying the container.
+ </p>
+
+ <p>Changes can be observed by registering a listener with interface
+ <type scope="com::sun::star::container">XContainer</type> (if available).
+ </p>
+
+ <p>If the elements of this set are of simple type (the type returned by
+ <member scope="com::sun::star::container">XElementAccess::getElementType</member>
+ is not an interface type), then values of that type can directly be passed to
+ <member scope="com::sun::star::container">XNameContainer::insertByName</member>
+ and
+ <member scope="com::sun::star::container">XNameContainer::replaceByName</member>.
+ </p>
+
+ <p>Otherwise new elements have to be constructed to match the type
+ prescribed by the element template of this set. Such elements can be created
+ using interfaces <type scope="com::sun::star::lang">XSingleServiceFactory</type>
+ and (if supported) <type scope="com::sun::star::lang">XMultiServiceFactory</type>.
+ </p>
+
+ <p>Objects to be inserted must not be contained in any set at the time of
+ insertion (<member scope="com::sun::star::container">XChild::getParent</member>
+ must return <NULL/>). A prior name they bear is ignored.
+ </p>
+
+ <p>Objects that are removed using
+ <member scope="com::sun::star::container">XNameContainer::removeByName</member>
+ or replaced using
+ <member scope="com::sun::star::container">XNameContainer::replaceByName</member>
+ remain valid and can be reinserted into a set supporting the same template
+ (even under a different name).
+ </p>
+
+ <p>An implementation need not support insertion of objects that weren't
+ obtained in one of the ways described above. If it does, the implementation
+ must reject elements that don't have the correct structure as described
+ by the template.
+ </p>
+*/
+    interface com::sun::star::container::XNameContainer;
+
+/** allows creating an object that can be inserted into this set. [conditional]
+
+ <p>This interface shall be implemented by an implementation,
+ if and only if the element type of the set (as returned by
+ <member scope="com::sun::star::container">XElementAccess::getElementType</member>)
+ is an object type (i.e. an interface).
+ </p>
+
+ <p>Using
+ <member scope="com::sun::star::lang">XSingleServiceFactory::createInstance</member>
+ an instance of the element template of this set is created. If the set
+ supports multiple templates or variatios of the basic template, a default
+ variant of the basic template is instantiated. If an implementation supports
+ variations, they may be specified by passing arguments to
+ <member scope="com::sun::star::lang">XSingleServiceFactory::createInstanceWithArguments</member>.
+ There are no predefined arguments for all versions of this service.
+ </p>
+
+ <p>The object created is not contained in the set and does not have a name yet.
+ It may subsequently be inserted into the set (and named) using
+ <member scope="com::sun::star::container">XNameContainer::insertByName</member>
+ or
+ <member scope="com::sun::star::container">XNameContainer::replaceByName</member>.
+ </p>
+*/
+    interface com::sun::star::lang::XSingleServiceFactory;
+
+/** allows creating various objects that can be inserted into this set. [optional]
+
+ <p>This interface may be implemented by an implementation of
+ service SetUpdate to support creating elements from other than
+ the basic element template. An example of this would be an
+ implementation that supports 'inheritance', allowing the use of
+ templates 'derived' from the basic template by extension.
+ </p>
+
+ <p>This interface may only be implemented, if the element type of the set
+ (as returned by
+ <member scope="com::sun::star::container">XElementAccess::getElementType</member>)
+ is an object type (i.e an interface). An implementation should also implement
+ interface <type>XTemplateContainer</type> (which also is optional in this service).
+ </p>
+
+ <p>The service identifier argument passed
+ to <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance</member>
+ or <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
+ names the template to be instantiated (or otherwise identifies the structure
+ to be built). The implementation must at least support using the template
+ name obtained from <member>XTemplateContainer::getElementTemplateName</member>
+ as a service identifier, in which case the result shall be the same as if
+ the corresponding member of <type scope="com::sun::star::lang">XSingleServiceFactory</type>
+ had been called.
+ </p>
+
+*/
+    interface com::sun::star::lang::XMultiServiceFactory;
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif
diff --git a/offapi/com/sun/star/configuration/UpdateRootElement.idl b/offapi/com/sun/star/configuration/UpdateRootElement.idl
new file mode 100644
index 000000000000..8a9a619d0b71
--- /dev/null
+++ b/offapi/com/sun/star/configuration/UpdateRootElement.idl
@@ -0,0 +1,144 @@
+/*************************************************************************
+ *
+ *  $RCSfile: UpdateRootElement.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: jb $ $Date: 2001-02-01 14:31:41 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_configuration_UpdateRootElement_idl__
+#define __com_sun_star_configuration_UpdateRootElement_idl__
+
+#ifndef __com_sun_star_configuration_AccessRootElement_idl__
+#include <com/sun/star/configuration/AccessRootElement.idl>
+#endif
+
+#ifndef __com_sun_star_util_XChangesBatch_idl__
+#include <com/sun/star/util/XChangesBatch.idl>
+#endif
+
+//=============================================================================
+
+module com { module sun { module star { module configuration {
+
+//=============================================================================
+/** provides update control for a (by name) hierarchy
+ and information about the hierarchy as a whole as well as its root.
+
+ <p>Extends <type>AccessRootElement</type> by adding support for
+ collecting changes and applying them to a backend store as a single batch.
+ </p>
+
+ <p>An implementation represents the root of a (partial) hierarchy. [see the
+ documentation for <type>AccessRootElement</type>]. The hierarchy in turn is
+ a <em>view</em> onto (a fragment of) persistent data tree that can be accessed
+ through several such views (or even several processes) simultaneously.
+ </p>
+
+ <p>Elements of the hierarchy (i.e. descendants of this root element)
+ may (and generally do) support modification by providing appropriate
+ interfaces. Changes done this way initially only affect these objects
+ themselves and other objects within the same hierarchy (i.e. other
+ descendants of this root element).
+ </p>
+
+ <p>The accumulated changes within this hierarchy can be managed using
+ <type scope="com::sun::star::util">XChangesBatch</type>. Pending changes
+ will become persistent (and visible from other, overlapping hierarchies)
+ only when <member scope="com::sun::star::util">XChangesBatch::commitChanges</member>
+ is called. If the hierarchy is disposed or discarded without committing
+ changes, the changes will be lost.
+ </p>
+
+ @see com::sun::star::configuration::GroupUpdate;
+ @see com::sun::star::configuration::SetUpdate;
+*/
+service UpdateRootElement
+{
+/** provides (read-only) access to information about the root element of
+ (a fragment of) the hierarchy. It also provides some functionality concerning
+ the hierarchy (fragment) accessible from that element as a whole.
+*/
+    service AccessRootElement;
+
+/** allows managing changes within the hierarchy.
+
+ <p><member scope="com::sun::star::util">XChangesBatch::getPendingChanges</member>
+ reports all changes within the hierarchy that are done through (direct or
+ indirect) descendants of this element. The same set of changes is committed
+ to persistent storage and/or made visible to other objects accessing the same
+ data set, when
+ <member scope="com::sun::star::util">XChangesBatch::commitChanges</member>
+ is invoked.
+ </p>
+
+ <p>If the implementation supports
+ <member scope="com::sun::star::lang">XLocalizable::setLocale</member>, changes
+ will be considered to apply to the locale that is set when
+ <member scope="com::sun::star::util">XChangesBatch::commitChanges</member>
+ is invoked.
+ </p>
+
+ @ see AccessRootElement
+ @ see com::sun::star::util::XChangesNotifier
+*/
+    interface com::sun::star::util::XChangesBatch;
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif