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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28 #ifndef __com_sun_star_configuration_SimpleSetUpdate_idl__
  29 #define __com_sun_star_configuration_SimpleSetUpdate_idl__
  30
  31 #include <com/sun/star/configuration/SimpleSetAccess.idl>
  32 #include <com/sun/star/container/XNameContainer.idl>
  33 #include <com/sun/star/lang/XSingleServiceFactory.idl>
  34 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  35
  36 //=============================================================================
  37
  38 module com { module sun { module star { module configuration {
  39
  40 //=============================================================================
  41 /** provides write access to a dynamic, homogeneous, non-hierarchical set of
  42  values or objects.
  43
  44  <p>Allows adding and removing elements.
  45  Helps create new elements to be added.
  46  </p>
  47
  48  <p>This service extends <type>SimpleSetAccess</type> to support
  49  modifying the container. Any child objects shall in turn support
  50  modifying access.
  51  </p>
  52 */
  53 published service SimpleSetUpdate
  54 {
  55 /** is the basic service providing read access to a (not necessarily
  56  hierarchical) <em>set</em>.
  57 */
  58     service SimpleSetAccess;
  59
  60 /** allows inserting, removing, and replacing elements.
  61
  62  <p>This interface extends the interface
  63  <type scope="com::sun::star::container">XNameAccess</type> supported
  64  by service <type>SimpleSetAccess</type> to allow modifying the container.
  65  </p>
  66
  67  <p>If available, changes can be observed by registering a listener with interface
  68  <type scope="com::sun::star::container">XContainer</type>.
  69  </p>
  70
  71  <p>If the elements of this set are of simple type (the type returned by
  72  <member scope="com::sun::star::container">XElementAccess::getElementType()</member>
  73  is not an interface type), then values of that type can directly be passed to
  74  <member scope="com::sun::star::container">XNameContainer::insertByName()</member>
  75  and
  76  <member scope="com::sun::star::container">XNameContainer::replaceByName()</member>.
  77  </p>
  78
  79  <p>Otherwise new elements have to be constructed to match the type
  80  prescribed by the element template of this set. Such elements can be created
  81  using interfaces <type scope="com::sun::star::lang">XSingleServiceFactory</type>
  82  and, if supported, <type scope="com::sun::star::lang">XMultiServiceFactory</type>.
  83  </p>
  84
  85  <p>Objects to be inserted must not be contained in any set at the time of
  86  insertion. <member scope="com::sun::star::container">XChild::getParent()</member>
  87  must return <NULL/>. If a name had been assigned to the object prior to insertion
  88  (using <member scope="com::sun::star::container">XNamed::setName()</member>
  89  or by other means), this name is ignored and will be lost.
  90  After insertion the name of the object is the name that was used as argument
  91  to <member scope="com::sun::star::container">XNameContainer::insertByName()</member>
  92  or <member scope="com::sun::star::container">XNameContainer::replaceByName()</member>.
  93 </p>
  94
  95
  96  <p>Objects that are removed using
  97  <member scope="com::sun::star::container">XNameContainer::removeByName()</member>
  98  or replaced using
  99  <member scope="com::sun::star::container">XNameContainer::replaceByName()</member>
 100  remain valid and can be reinserted into a set supporting the same template and
 101  even under a different name.
 102  </p>
 103
 104  <p>An implementation need not support insertion of objects that were not
 105  obtained in one of the ways described above. If it does, the implementation
 106  must reject elements that do not have the correct structure as described
 107  by the template.
 108  </p>
 109 */
 110     interface com::sun::star::container::XNameContainer;
 111
 112 /** allows creating an object that can be inserted into this set. [conditional]
 113
 114  <p>This interface shall be implemented by an implementation,
 115  if and only if the element type of the set, as returned by
 116  <member scope="com::sun::star::container">XElementAccess::getElementType()</member>,
 117  is an object type, such as an interface.
 118  </p>
 119
 120  <p>Using <member scope="com::sun::star::lang">XSingleServiceFactory::createInstance()</member>
 121  an instance of the element template of this set is created. If the set
 122  supports multiple templates or variations of the basic template, a default
 123  variant of the basic template is instantiated. If an implementation supports
 124  variations, they may be specified by passing arguments to
 125  <member scope="com::sun::star::lang">XSingleServiceFactory::createInstanceWithArguments()</member>.
 126  There are no predefined arguments for all versions of this service.
 127  </p>
 128
 129  <p>The object created is not contained in the set and does not have a name yet.
 130  It may subsequently be inserted into the set and named using
 131  <member scope="com::sun::star::container">XNameContainer::insertByName()</member>
 132  or
 133  <member scope="com::sun::star::container">XNameContainer::replaceByName()</member>.
 134  </p>
 135 */
 136     [optional] interface com::sun::star::lang::XSingleServiceFactory;
 137
 138 /** allows creating various objects that can be inserted into this set. [optional]
 139
 140  <p>This interface may be implemented by an implementation of
 141  service SetUpdate to support creating elements from other than
 142  the basic element template. An example of this would be an
 143  implementation that supports inheritance, allowing the use of
 144  templates derived from the basic template by extension.
 145  </p>
 146
 147  <p>This interface may only be implemented if the element type of the set
 148  (as returned by
 149  <member scope="com::sun::star::container">XElementAccess::getElementType()</member>)
 150  is an object type, such as an interface. An implementation should also implement
 151  interface <type>XTemplateContainer</type> which is optional in this service.
 152  </p>
 153
 154  <p>The service identifier argument passed
 155  to <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member>
 156  or <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member>
 157  names the template to be instantiated or otherwise identifies the structure
 158  to be built. The implementation must at least support using the template
 159  name obtained from <member>XTemplateContainer::getElementTemplateName()</member>
 160  as a service identifier, in which case the result shall be the same as if
 161  the corresponding member of <type scope="com::sun::star::lang">XSingleServiceFactory</type>
 162  had been called.
 163  </p>
 164
 165 */
 166     [optional] interface com::sun::star::lang::XMultiServiceFactory;
 167
 168 };
 169
 170 //=============================================================================
 171
 172 }; }; }; };
 173
 174 #endif
 175
 176 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */