offapi/com/sun/star/configuration/ConfigurationUpdateAccess.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /**
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_configuration_ConfigurationUpdateAccess_idl__
  20 #define __com_sun_star_configuration_ConfigurationUpdateAccess_idl__
  21
  22 #include <com/sun/star/configuration/ConfigurationAccess.idl>
  23 #include <com/sun/star/configuration/SetUpdate.idl>
  24 #include <com/sun/star/configuration/GroupUpdate.idl>
  25 #include <com/sun/star/configuration/UpdateRootElement.idl>
  26
  27
  28 module com { module sun { module star { module configuration {
  29
  30 /** provides modifying access to a fragment of the configuration hierarchy.
  31
  32  <p>Extends <type>ConfigurationAccess</type> to support modifying values
  33  or inserting and removing elements.
  34  </p>
  35
  36  <p>Descendants of this service also implement this service
  37  unless they are marked <em>read-only</em> (which is indicated by attribute
  38  <const scope="com::sun::star::beans">PropertyAttribute::READONLY</const>),
  39  in which case they only need implement <type>ConfigurationAccess</type>.
  40  </p>
  41
  42  <p>The classification of implementations that is described for
  43  <type>ConfigurationAccess</type> applies to implementations of this service
  44  as well. Therefore an implementation will support one of several alternate
  45  services describing its <em>Container</em> role and one of several alternate
  46  services describing its <em>Element</em> role. These services are
  47  extensions of the respective services documented for <type>ConfigurationAccess</type>.
  48  </p>
  49  <ul>
  50     <li><em>Container</em> role:
  51         A <em>group</em> permits changing child values.
  52         A <em>set</em> permits inserting and removing contained elements.
  53     </li>
  54     <li><em>Element</em> role:
  55         The root element of a modifiable tree provides extended functionality
  56         to control processing of changes for the entire tree (fragment) by
  57         supporting <type scope="com::sun::star::util">XChangesBatch</type>.
  58         For elements of a <em>set</em> or a <em>group</em> no additional
  59         interfaces are supported.
  60     </li>
  61  </ul>
  62
  63  @see ConfigurationProvider
  64     Root instances of this service can be requested from a
  65     <type>ConfigurationProvider</type>
  66 */
  67 published service ConfigurationUpdateAccess
  68 {
  69     /** is the basic service providing read access to an element of the
  70      configuration hierarchy and its child and descendent elements.
  71
  72      <p>The <type>HierarchyAccess</type> specialization implemented will be
  73      further specialized to support modifying access.
  74      Implementations shall therefore implement one of <type>SetUpdate</type> or
  75      <type>GroupUpdate</type> depending on the <em>Container</em> role.
  76      </p>
  77
  78      <p>If the <type>HierarchyElement</type> specialization that is implemented
  79      is <type>AccessRootElement</type>, the implementation must support the
  80      extended functionality of <type>UpdateRootElement</type>. Otherwise, there
  81      are no new requirements mandated by the <em>Element</em> role.
  82      </p>
  83
  84     */
  85     service ConfigurationAccess;
  86
  87     /** specializes <type>SetAccess</type> to support modifying the element.
  88
  89      <p>Implemented, if this element is a <em>Set</em>.
  90      Otherwise service <type>GroupUpdate</type> is provided.
  91      </p>
  92     */
  93     [optional] service SetUpdate;
  94
  95     /** specializes <type>GroupAccess</type> to support modifying contained
  96      data.
  97
  98      <p>Implemented, if this element is a <em>Group</em>.
  99      Otherwise service <type>SetUpdate</type> is provided.
 100      </p>
 101     */
 102     [optional] service GroupUpdate;
 103
 104     /** specializes <type>AccessRootElement</type> to support transaction-like
 105      control over a batch of changes accumulated within the tree fragment.
 106
 107      <p>Implemented, if this element is the <em>Root</em> of the whole hierarchy.
 108      Otherwise either <type>SetElement</type> or <type>GroupElement</type> is provided.
 109      </p>
 110
 111      @see ConfigurationProvider
 112         Instances obtained from a <type>ConfigurationProvider</type> will
 113         implement this version of <type>HierarchyElement</type>.
 114     */
 115     [optional] service UpdateRootElement;
 116 };
 117
 118
 119 }; }; }; };
 120
 121 #endif
 122
 123 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */