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

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