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