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_backend_XMultiLayerStratum_idl__ 24#define __com_sun_star_configuration_backend_XMultiLayerStratum_idl__ 25 26#ifndef __com_sun_star_uno_XInterface_idl__ 27#include <com/sun/star/uno/XInterface.idl> 28#endif 29 30#ifndef __com_sun_star_configuration_backend_XLayer_idl__ 31#include <com/sun/star/configuration/backend/XLayer.idl> 32#endif 33 34#ifndef __com_sun_star_configuration_backend_XUpdatableLayer_idl__ 35#include <com/sun/star/configuration/backend/XUpdatableLayer.idl> 36#endif 37 38#ifndef __com_sun_star_configuration_backend_BackendAccessException_idl__ 39#include <com/sun/star/configuration/backend/BackendAccessException.idl> 40#endif 41 42#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ 43#include <com/sun/star/lang/IllegalArgumentException.idl> 44#endif 45 46#ifndef __com_sun_star_lang_NoSupportException_idl__ 47#include <com/sun/star/lang/NoSupportException.idl> 48#endif 49 50//============================================================================= 51 52module com { module sun { module star { module configuration { module backend { 53 54//============================================================================= 55 56/** 57 Handles access to a stratum consisting of multiple layers 58 in a single configuration data repository 59 60 <p> The interface provides access to data for multiple entities and 61 timestamp-checking capabilities for efficient caching. 62 </p> 63 64 @see com::sun::star::configuration::backend::XBackendEntities 65 @see com::sun::star::util::XTimeStamped 66 @see com::sun::star::configuration::backend::XSchemaSupplier 67 @see com::sun::star::configuration::backend::XSingleLayerStratum 68 69 @since OpenOffice 1.1.2 70*/ 71published interface XMultiLayerStratum : ::com::sun::star::uno::XInterface 72{ 73 //------------------------------------------------------------------------- 74 75 /** 76 identifies the layers within this stratum which should be read and 77 merged to determine data of a component for an entity 78 79 80 @param aComponent 81 The name of the component to access. 82 83 @param aEntity 84 The name of an entity on behalf of which data will be accessed. 85 86 @return 87 a list of layer identifiers that can be used to 88 retrieve <type>Layer</type> objects. 89 <p> The list ist ordered by priority. Typically 90 the most general layers (global defaults, 91 entire organization) are first, more specific layers 92 (associated to specific groups or roles) are next 93 and the entity's own data is last. 94 </p> 95 96 @throws com::sun::star::lang::IllegalArgumentException 97 if the component identifier is invalid or 98 if the entity doesn't exist. 99 100 @throws com::sun::star::configuration::backend::BackendAccessException 101 if an error occurs while accessing the data. 102 103 @see com::sun::star::configuration::backend::XMultiLayerStratum::getLayer() 104 @see com::sun::star::configuration::backend::XMultiLayerStratum::getLayers() 105 @see com::sun::star::configuration::backend::XMultiLayerStratum::getMultipleLayers() 106 @see com::sun::star::configuration::backend::XBackendEntities 107 */ 108 sequence<string> listLayerIds([in] string aComponent, 109 [in] string aEntity) 110 raises (BackendAccessException, 111 com::sun::star::lang::IllegalArgumentException) ; 112 113 //------------------------------------------------------------------------- 114 115 /** 116 identifies the layer which should be modified 117 to update data of a component on behalf of an entity. 118 119 <p> The layer id returned is one of the layer ids obtained from 120 <member>XMultiLayerStratum::listLayerIds()</member> for the same 121 component and entity. 122 </p> 123 124 @param aComponent 125 The name of the component to access. 126 127 @param aEntity 128 The name of an entity on behalf of which data will be accessed. 129 130 @returns 131 a layer identifier that can be used to obtain 132 an <type>UpdatableLayer</type> object. 133 134 @throws com::sun::star::lang::IllegalArgumentException 135 if the component identifier is invalid or 136 if the entity doesn't exist. 137 138 @throws com::sun::star::lang::NoSupportException 139 if the implementation does not support updates. 140 141 @throws com::sun::star::configuration::backend::BackendAccessException 142 if an error occurs while accessing the data. 143 144 @see com::sun::star::configuration::backend::XMultiLayerStratum::getUpdatableLayer() 145 @see com::sun::star::configuration::backend::XBackendEntities 146 */ 147 string getUpdateLayerId([in] string aComponent, 148 [in] string aEntity) 149 raises (BackendAccessException, 150 com::sun::star::lang::NoSupportException, 151 com::sun::star::lang::IllegalArgumentException) ; 152 153 //------------------------------------------------------------------------- 154 155 /** 156 retrieves a layer associated to a layer id, if newer than indicated. 157 158 <p> A timestamp can be provided, which is used to indicate 159 a point in time. The layer should be returned only if is modified 160 since that time. 161 </p> 162 163 @param aLayerId 164 identifier of the layers to be accessed. 165 <p>Layer ids can be obtained from 166 <member>XMultiLayerStratum::listLayerIds()</member> or 167 <member>XMultiLayerStratum::getUpdateLayerId()</member>. 168 </p> 169 170 @param aTimestamp 171 a timestamp for the layer. 172 173 <p> An empty timestamp indicates, that the layer should be 174 retrieved irrespective of its modification time. 175 </p> 176 <p> The format and meaning of a timestamp depends on 177 the implementation. Timestamps can be obtained using 178 <member scope="com::sun::star::util">XTimeStamped::getTimestamp()</member>. 179 </p> 180 181 @returns 182 a <type>Layer</type> object providing access to the layer data, 183 <NULL/> if the layer is newer than indicated by the timestamp. 184 185 @throws com::sun::star::lang::IllegalArgumentException 186 if the layer id is invalid or 187 if the timestamp is invalid 188 189 @throws com::sun::star::configuration::backend::BackendAccessException 190 if an error occurs while accessing the data. 191 192 @see com::sun::star::util::XTimeStamped 193 */ 194 XLayer getLayer([in] string aLayerId, 195 [in] string aTimestamp) 196 raises (BackendAccessException, 197 com::sun::star::lang::IllegalArgumentException) ; 198 199 //------------------------------------------------------------------------- 200 201 /** 202 retrieves the layers associated to a series of layer ids, 203 if newer than indicated. 204 <p> A timestamp can be provided, which is used to indicate 205 a point in time. Only layers that are modified since that time 206 should be returned. The same timestamp is used for all layers. 207 </p> 208 209 @param aLayerIds 210 identifiers of the layers to be accessed. 211 <p>Layer ids can be obtained from 212 <member>XMultiLayerStratum::listLayerIds()</member>. 213 </p> 214 215 @param aTimestamp 216 a timestamp for all of the layers. 217 <p> An empty timestamp indicates, that the layers should be 218 retrieved irrespective of their modification time. 219 </p> 220 <p> The format and meaning of a timestamp depends on 221 the implementation. Timestamps can be obtained using 222 <member scope="com::sun::star::util">XTimeStamped::getTimestamp()</member>. 223 </p> 224 225 @returns 226 a list of <type>Layer</type> objects 227 providing access to the layer data. 228 <p> The list has the same length as aLayerIds. Each layer 229 object is associated to the layer id in the corresponding 230 position. 231 </p> 232 <p> For layers that are newer than indicated by the 233 timestamp, the list contains a <NULL/> element. 234 </p> 235 236 @throws com::sun::star::lang::IllegalArgumentException 237 if one of the layer ids is invalid or 238 if the timestamp is invalid 239 240 @throws com::sun::star::configuration::backend::BackendAccessException 241 if an error occurs while accessing the data. 242 243 @see com::sun::star::util::XTimeStamped 244 */ 245 sequence<XLayer> getLayers([in] sequence<string> aLayerIds, 246 [in] string aTimestamp) 247 raises (BackendAccessException, 248 com::sun::star::lang::IllegalArgumentException) ; 249 250 //------------------------------------------------------------------------- 251 252 /** 253 retrieves the layers associated to a series of layer ids, 254 if newer than indicated for each layer. 255 <p> For each layer an individual timestamp can be provided, 256 which is used to indicate the last known version of the layer. 257 Only layers that are modified since that time should be returned. 258 </p> 259 260 @param aLayerIds 261 identifiers of the layers to be accessed. 262 <p>Layer ids can be obtained from 263 <member>XMultiLayerStratum::listLayerIds()</member>. 264 </p> 265 266 @param aTimestamps 267 timestamps for each of the layers. 268 269 <p> This list must have the same length as aLayerIds. 270 Timestamps are matched to layer ids by their position. 271 </p> 272 <p> An empty timestamp indicates, that the associated layer 273 should be retrieved irrespective of its modification time. 274 </p> 275 <p> The format and meaning of a timestamp depends on 276 the implementation. Timestamps can be obtained using 277 <member scope="com::sun::star::util">XTimeStamped::getTimestamp()</member>. 278 </p> 279 280 @returns 281 a list of <type>Layer</type> objects 282 providing access to the layer data. 283 <p> The list has the same length as aLayerIds. Each layer 284 object is associated to the layer id in the corresponding 285 position. 286 </p> 287 <p> For layers that are newer than indicated by the corresponding 288 timestamp, the list contains a <NULL/> element. 289 </p> 290 291 @throws com::sun::star::lang::IllegalArgumentException 292 if one of the layer ids is invalid or 293 if one of the timestamps is invalid or 294 if the lengths of the arguments don't match. 295 296 @throws com::sun::star::configuration::backend::BackendAccessException 297 if an error occurs while accessing the data. 298 299 @see com::sun::star::util::XTimeStamped 300 */ 301 sequence<XLayer> getMultipleLayers([in] sequence<string> aLayerIds, 302 [in] sequence<string> aTimestamps) 303 raises (BackendAccessException, 304 com::sun::star::lang::IllegalArgumentException) ; 305 306 //------------------------------------------------------------------------- 307 308 /** 309 retrieves a writable representation of the layer 310 associated to a layer id. 311 312 @param aLayerId 313 identifier of the layer to be accessed for writing. 314 <p>A layer id for writing can be obtained from 315 <member>XMultiLayerStratum::getUpdateLayerId()</member>. 316 </p> 317 318 @return 319 an <type>UpdatableLayer</type> object providing 320 write access to the layer 321 322 @throws com::sun::star::lang::IllegalArgumentException 323 if the layer id is invalid. 324 325 @throws com::sun::star::lang::NoSupportException 326 if the implementation does not support updates. 327 328 @throws com::sun::star::configuration::backend::BackendAccessException 329 if an error occurs while accessing the data. 330 */ 331 XUpdatableLayer getUpdatableLayer([in] string aLayerId) 332 raises (BackendAccessException, 333 com::sun::star::lang::NoSupportException, 334 com::sun::star::lang::IllegalArgumentException) ; 335 336 //------------------------------------------------------------------------- 337} ; 338 339//============================================================================= 340 341} ; } ; } ; } ; } ; 342 343#endif 344