1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: XMultiLayerStratum.idl,v $
12 * This file is part of OpenOffice.org.
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.
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).
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.
29 ************************************************************************/
30 #ifndef __com_sun_star_configuration_backend_XMultiLayerStratum_idl__
31 #define __com_sun_star_configuration_backend_XMultiLayerStratum_idl__
33 #ifndef __com_sun_star_uno_XInterface_idl__
34 #include
<com
/sun
/star
/uno
/XInterface.idl
>
37 #ifndef __com_sun_star_configuration_backend_XLayer_idl__
38 #include
<com
/sun
/star
/configuration
/backend
/XLayer.idl
>
41 #ifndef __com_sun_star_configuration_backend_XUpdatableLayer_idl__
42 #include
<com
/sun
/star
/configuration
/backend
/XUpdatableLayer.idl
>
45 #ifndef __com_sun_star_configuration_backend_BackendAccessException_idl__
46 #include
<com
/sun
/star
/configuration
/backend
/BackendAccessException.idl
>
49 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
50 #include
<com
/sun
/star
/lang
/IllegalArgumentException.idl
>
53 #ifndef __com_sun_star_lang_NoSupportException_idl__
54 #include
<com
/sun
/star
/lang
/NoSupportException.idl
>
57 //=============================================================================
59 module com
{ module sun
{ module star
{ module configuration
{ module backend
{
61 //=============================================================================
64 Handles access to a stratum consisting of multiple layers
65 in a single configuration data repository
67 <p> The interface provides access to data for multiple entities and
68 timestamp-checking capabilities for efficient caching.
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
78 published
interface XMultiLayerStratum
: ::com
::sun
::star
::uno
::XInterface
80 //-------------------------------------------------------------------------
83 identifies the layers within this stratum which should be read and
84 merged to determine data of a component for an entity
88 The name of the component to access.
91 The name of an entity on behalf of which data will be accessed.
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.
103 @throws com::sun::star::lang::IllegalArgumentException
104 if the component identifier is invalid or
105 if the entity doesn't exist.
107 @throws com::sun::star::configuration::backend::BackendAccessException
108 if an error occurs while accessing the data.
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
115 sequence
<string> listLayerIds
([in] string aComponent
,
117 raises
(BackendAccessException
,
118 com
::sun
::star
::lang
::IllegalArgumentException
) ;
120 //-------------------------------------------------------------------------
123 identifies the layer which should be modified
124 to update data of a component on behalf of an entity.
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.
132 The name of the component to access.
135 The name of an entity on behalf of which data will be accessed.
138 a layer identifier that can be used to obtain
139 an <type>UpdatableLayer</type> object.
141 @throws com::sun::star::lang::IllegalArgumentException
142 if the component identifier is invalid or
143 if the entity doesn't exist.
145 @throws com::sun::star::lang::NoSupportException
146 if the implementation does not support updates.
148 @throws com::sun::star::configuration::backend::BackendAccessException
149 if an error occurs while accessing the data.
151 @see com::sun::star::configuration::backend::XMultiLayerStratum::getUpdatableLayer()
152 @see com::sun::star::configuration::backend::XBackendEntities
154 string getUpdateLayerId
([in] string aComponent
,
156 raises
(BackendAccessException
,
157 com
::sun
::star
::lang
::NoSupportException
,
158 com
::sun
::star
::lang
::IllegalArgumentException
) ;
160 //-------------------------------------------------------------------------
163 retrieves a layer associated to a layer id, if newer than indicated.
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
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>.
178 a timestamp for the layer.
180 <p> An empty timestamp indicates, that the layer should be
181 retrieved irrespective of its modification time.
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>.
189 a <type>Layer</type> object providing access to the layer data,
190 <NULL/> if the layer is newer than indicated by the timestamp.
192 @throws com::sun::star::lang::IllegalArgumentException
193 if the layer id is invalid or
194 if the timestamp is invalid
196 @throws com::sun::star::configuration::backend::BackendAccessException
197 if an error occurs while accessing the data.
199 @see com::sun::star::util::XTimeStamped
201 XLayer getLayer
([in] string aLayerId
,
202 [in] string aTimestamp
)
203 raises
(BackendAccessException
,
204 com
::sun
::star
::lang
::IllegalArgumentException
) ;
206 //-------------------------------------------------------------------------
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.
217 identifiers of the layers to be accessed.
218 <p>Layer ids can be obtained from
219 <member>XMultiLayerStratum::listLayerIds()</member>.
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.
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>.
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
239 <p> For layers that are newer than indicated by the
240 timestamp, the list contains a <NULL/> element.
243 @throws com::sun::star::lang::IllegalArgumentException
244 if one of the layer ids is invalid or
245 if the timestamp is invalid
247 @throws com::sun::star::configuration::backend::BackendAccessException
248 if an error occurs while accessing the data.
250 @see com::sun::star::util::XTimeStamped
252 sequence
<XLayer
> getLayers
([in] sequence
<string> aLayerIds
,
253 [in] string aTimestamp
)
254 raises
(BackendAccessException
,
255 com
::sun
::star
::lang
::IllegalArgumentException
) ;
257 //-------------------------------------------------------------------------
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.
268 identifiers of the layers to be accessed.
269 <p>Layer ids can be obtained from
270 <member>XMultiLayerStratum::listLayerIds()</member>.
274 timestamps for each of the layers.
276 <p> This list must have the same length as aLayerIds.
277 Timestamps are matched to layer ids by their position.
279 <p> An empty timestamp indicates, that the associated layer
280 should be retrieved irrespective of its modification time.
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>.
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
294 <p> For layers that are newer than indicated by the corresponding
295 timestamp, the list contains a <NULL/> element.
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.
303 @throws com::sun::star::configuration::backend::BackendAccessException
304 if an error occurs while accessing the data.
306 @see com::sun::star::util::XTimeStamped
308 sequence
<XLayer
> getMultipleLayers
([in] sequence
<string> aLayerIds
,
309 [in] sequence
<string> aTimestamps
)
310 raises
(BackendAccessException
,
311 com
::sun
::star
::lang
::IllegalArgumentException
) ;
313 //-------------------------------------------------------------------------
316 retrieves a writable representation of the layer
317 associated to a layer id.
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>.
326 an <type>UpdatableLayer</type> object providing
327 write access to the layer
329 @throws com::sun::star::lang::IllegalArgumentException
330 if the layer id is invalid.
332 @throws com::sun::star::lang::NoSupportException
333 if the implementation does not support updates.
335 @throws com::sun::star::configuration::backend::BackendAccessException
336 if an error occurs while accessing the data.
338 XUpdatableLayer getUpdatableLayer
([in] string aLayerId
)
339 raises
(BackendAccessException
,
340 com
::sun
::star
::lang
::NoSupportException
,
341 com
::sun
::star
::lang
::IllegalArgumentException
) ;
343 //-------------------------------------------------------------------------
346 //=============================================================================