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