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