offapi/com/sun/star/configuration/backend/XLayerHandler.idl

   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_XLayerHandler_idl__
  28 #define __com_sun_star_configuration_backend_XLayerHandler_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_TemplateIdentifier_idl__
  35 #include <com/sun/star/configuration/backend/TemplateIdentifier.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_configuration_backend_MalformedDataException_idl__
  39 #include <com/sun/star/configuration/backend/MalformedDataException.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_lang_WrappedTargetException_idl__
  43 #include <com/sun/star/lang/WrappedTargetException.idl>
  44 #endif
  45
  46 //=============================================================================
  47
  48 module com { module sun { module star { module configuration { module backend {
  49
  50 //=============================================================================
  51
  52 /** receives a description of a configuration layer
  53     as a sequence of events.
  54
  55     @since OOo 1.1.2
  56  */
  57 published interface XLayerHandler: ::com::sun::star::uno::XInterface
  58 {
  59     //-------------------------------------------------------------------------
  60
  61     /** receives notification that a layer description is started
  62         for a component.
  63
  64         <p> Subsequent calls describe the contents of the layer
  65             until a matching call to <member>XLayerHandler::endLayer()</member>
  66             is encountered.
  67         </p>
  68
  69         @throws com::sun::star::configuration::backend::MalformedDataException
  70             if there is an unfinished layer in progress
  71
  72         @throws com::sun::star::lang::WrappedTargetException
  73             if an error occurs processing the event.
  74      */
  75     void startLayer(  )
  76             raises( MalformedDataException,
  77                     com::sun::star::lang::WrappedTargetException );
  78     //-------------------------------------------------------------------------
  79
  80     /** receives notification that a layer description is complete.
  81
  82         <p> Must match a previous call to <member>XLayerHandler::startLayer()</member>.
  83         </p>
  84
  85         @throws com::sun::star::configuration::backend::MalformedDataException
  86             <ul>
  87             <li>if invalid data is detected in the layer</li>
  88             <li>if there is a unfinished subnode in progress</li>
  89             <li>if no layer is started at all</li>
  90             <li>if the layer tries to override read-only or final data</li>
  91             </ul>
  92             <p><em>Not every implementation can detect each condition</em></p>
  93
  94         @throws com::sun::star::lang::WrappedTargetException
  95             if an error occurs processing the event.
  96      */
  97     void endLayer(  )
  98             raises( MalformedDataException,
  99                     com::sun::star::lang::WrappedTargetException );
 100     //-------------------------------------------------------------------------
 101
 102     /** receives notification that a description of a node override is started.
 103
 104         <p> Subsequent calls describe overrides to properties and members
 105             or items of the node until a matching call to
 106             <member>XLayerHandler::endNode()</member>is encountered.
 107         </p>
 108
 109         @param aName
 110             specifies the name of the node.
 111
 112         @param aAttributes
 113             specifies attribute values to be applied to the node.
 114
 115             <p> The value is a combination of
 116                 <type>NodeAttribute</type> flags.
 117             </p>
 118             <p> The attributes are combined cumulatively with those
 119                 set on lower layers.
 120             </p>
 121
 122         @param bClear
 123             if <TRUE/>, specifies that the node should be cleared to an empty
 124             state by removing all non-mandatory children from lower layers prior
 125             to applying the overrides.
 126
 127         @throws com::sun::star::configuration::backend::MalformedDataException
 128             <ul>
 129             <li>if there isn't a layer in progress</li>
 130             <li>if there already was a change to that node</li>
 131             <li>if there is no node with that name</li>
 132             <li>if the node is marked read-only in a lower layer</li>
 133             <li>if the name is not a valid node name</li>
 134             <li>if the attributes are not valid for the node</li>
 135             </ul>
 136             <p><em>Not every implementation can detect each condition</em></p>
 137
 138         @throws com::sun::star::lang::WrappedTargetException
 139             if an error occurs processing the event.
 140
 141         @see com::sun::star::configuration::backend::NodeAttribute
 142      */
 143     void overrideNode( [in] string aName,
 144                        [in] short  aAttributes,
 145                        [in] boolean bClear )
 146             raises( MalformedDataException,
 147                     com::sun::star::lang::WrappedTargetException );
 148     //-------------------------------------------------------------------------
 149
 150     /** receives notification that a new item is started.
 151
 152         <p> The current node must be a set and
 153             a preexisting item (if any) must be removeable.
 154         </p>
 155         <p> The new item will be created from the default template
 156             of the set.
 157         </p>
 158         <p> Subsequent calls describe the difference from the template
 159             of properties and members or items of the node until
 160             a matching call to <member>XLayerHandler::endNode()</member>
 161             is encountered.
 162         </p>
 163
 164         @param aName
 165             specifies the name of the item.
 166
 167         @param aAttributes
 168             specifies attribute values to be applied to the new node.
 169
 170             <p> The value is a combination of
 171                 <type>NodeAttribute</type> flags.  Note that
 172                 <member>NodeAttribute::FUSE</member> has an impact on the
 173                 semantics of this method.
 174             </p>
 175
 176         @throws com::sun::star::configuration::backend::MalformedDataException
 177             <ul>
 178             <li>if there isn't a set node in progress currently</li>
 179             <li>if there already was a change to a node of that name</li>
 180             <li>if the template for the new node is not found</li>
 181             <li>if an item of that name on a lower layer is not removeable</li>
 182             <li>if the name is not a valid item name</li>
 183             <li>if the attributes are not valid for the node</li>
 184             </ul>
 185             <p><em>Not every implementation can detect each condition</em></p>
 186
 187         @throws com::sun::star::lang::WrappedTargetException
 188             if an error occurs processing the event.
 189
 190         @see com::sun::star::configuration::backend::NodeAttribute
 191      */
 192     void addOrReplaceNode(  [in] string aName,
 193                             [in] short  aAttributes )
 194             raises( MalformedDataException,
 195                     com::sun::star::lang::WrappedTargetException );
 196     //-------------------------------------------------------------------------
 197
 198     /** receives notification that a new item based on a particular template
 199         is started.
 200
 201         <p> The current node must be a set and
 202             a preexisting item (if any) must be removeable.
 203         </p>
 204         <p> Subsequent calls describe the difference from the template
 205             of properties and members or items of the node until
 206             a matching call to <member>XLayerHandler::endNode()</member>
 207             is encountered.
 208         </p>
 209
 210         @param aName
 211             specifies the name of the item.
 212
 213         @param aTemplate
 214             specifies the template to use for the new node
 215
 216         @param aAttributes
 217             specifies attribute values to be applied to the new node.
 218
 219             <p> The value is a combination of
 220                 <type>NodeAttribute</type> flags.  Note that
 221                 <member>NodeAttribute::FUSE</member> has an impact on the
 222                 semantics of this method.
 223             </p>
 224
 225         @throws com::sun::star::configuration::backend::MalformedDataException
 226             <ul>
 227             <li>if there isn't a set node in progress currently</li>
 228             <li>if there already was a change to a node of that name</li>
 229             <li>if the template for the new node is not found</li>
 230             <li>if the template is not a valid item type for the containing set</li>
 231             <li>if an item of that name on a lower layer is not removeable</li>
 232             <li>if the name is not a valid item name</li>
 233             <li>if the attributes are not valid for the node</li>
 234             </ul>
 235             <p><em>Not every implementation can detect each condition</em></p>
 236
 237         @throws com::sun::star::lang::WrappedTargetException
 238             if an error occurs processing the event.
 239
 240         @see com::sun::star::configuration::backend::NodeAttribute
 241      */
 242     void addOrReplaceNodeFromTemplate(  [in] string aName,
 243                                         [in] TemplateIdentifier aTemplate,
 244                                         [in] short  aAttributes )
 245             raises( MalformedDataException,
 246                     com::sun::star::lang::WrappedTargetException );
 247     //-------------------------------------------------------------------------
 248
 249     /** receives notification that a node description is complete.
 250
 251         <p> Must match the last open call to
 252             <member>XLayerHandler::overrideNode()</member>,
 253             <member>XLayerHandler::addOrReplaceNode()</member> or
 254             <member>XLayerHandler::addOrReplaceNodeFromTemplate()</member>.
 255         </p>
 256
 257         @throws com::sun::star::configuration::backend::MalformedDataException
 258             <ul>
 259             <li>if invalid data is detected in the node</li>
 260             <li>if no node is started at all</li>
 261             </ul>
 262             <p><em>Not every implementation can detect each condition</em></p>
 263
 264         @throws com::sun::star::lang::WrappedTargetException
 265             if an error occurs processing the event.
 266      */
 267     void endNode(  )
 268             raises( MalformedDataException,
 269                     com::sun::star::lang::WrappedTargetException );
 270     //-------------------------------------------------------------------------
 271
 272     /** receives notification that a node is dropped from a set.
 273
 274         <p> The current node must be a set and
 275             the item must be removeable.
 276         </p>
 277
 278         @param aName
 279             specifies the name of the node.
 280
 281         @throws com::sun::star::configuration::backend::MalformedDataException
 282             <ul>
 283             <li>if there isn't a set node in progress currently</li>
 284             <li>if there already was a change to a node of that name</li>
 285             <li>if there is no item with that name</li>
 286             <li>if the item is not removeable</li>
 287             <li>if the name is not a valid node name</li>
 288             </ul>
 289             <p><em>Not every implementation can detect each condition</em></p>
 290
 291         @throws com::sun::star::lang::WrappedTargetException
 292             if an error occurs processing the event.
 293      */
 294     void dropNode( [in] string aName )
 295             raises( MalformedDataException,
 296                     com::sun::star::lang::WrappedTargetException );
 297     //-------------------------------------------------------------------------
 298
 299     /** receives notification that an existing property is modified.
 300
 301         <p> Subsequent calls describe new value(s) for the property until a
 302             matching call to <member>XLayerHandler::endProperty()</member>
 303             is encountered.
 304         </p>
 305
 306         @param aName
 307             specifies the name of the property.
 308
 309         @param aAttributes
 310             specifies the new attributes of the property.
 311
 312             <p> The value is a combination of
 313                 <type>NodeAttribute</type> flags.
 314             </p>
 315             <p> The attributes are combined cumulatively with those
 316                 set on lower layers.
 317             </p>
 318
 319         @param aType
 320             specifies the type of the property.
 321
 322             <p> This must be the same type as is already defined in the schema
 323                 or lower layers, unless the previous type was unspecified
 324                 (as indicated by
 325                 <const scope="com::sun::star::uno">TypeClass::ANY</const>.)
 326             </p>
 327             <p> A <void/> type indicates that the type is unspecified
 328                 in this layer.
 329                 In this case any subsequent value may be of a generic type
 330                 (e.g. <atom>string</atom> or - for list values -
 331                 <atom dim="[]">string</atom>.) Such values may be
 332                 converted to the type defined in the schema by
 333                 the implementation.
 334             </p>
 335
 336         @param bClear
 337             if <TRUE/>, specifies that the property should be cleared to an empty
 338             state by discarding all values from lower layers prior
 339             to applying the overrides.
 340
 341         @throws com::sun::star::configuration::backend::MalformedDataException
 342             <ul>
 343             <li>if there isn't a group or extensible node in progress currently</li>
 344             <li>if there already was a change to a property of that name</li>
 345             <li>if there is no property with that name</li>
 346             <li>if the property is read-only</li>
 347             <li>if the type does not match the type of the property</li>
 348             <li>if a type is missing and cannot be determined otherwise</li>
 349             <li>if the name is not a valid property name</li>
 350             <li>if the attributes are not valid for the property</li>
 351             </ul>
 352             <p><em>Not every implementation can detect each condition</em></p>
 353
 354         @throws com::sun::star::lang::WrappedTargetException
 355             if an error occurs processing the event.
 356
 357         @see com::sun::star::configuration::backend::NodeAttribute
 358      */
 359     void overrideProperty(  [in] string aName,
 360                              [in] short aAttributes,
 361                             [in] type aType,
 362                             [in] boolean bClear )
 363             raises( MalformedDataException,
 364                     com::sun::star::lang::WrappedTargetException );
 365
 366     //-------------------------------------------------------------------------
 367
 368     /** receives notification that the value of the current property
 369         is overridden. .
 370
 371         @param aValue
 372             specifies the new value of the property.
 373
 374             <p> The value must match the type of the current property.
 375                 If the property does not have the
 376                 <const>SchemaAttribute::REQUIRED</const> flag set,
 377                 the value can be <void/>.
 378             </p>
 379             <p> If the current property is localized, this value applies
 380                 to the default locale.
 381             </p>
 382
 383         @throws com::sun::star::configuration::backend::MalformedDataException
 384             <ul>
 385             <li>if there isn't a property in progress currently</li>
 386             <li>if there already was a change to the value of that property</li>
 387             <li>if the value does not have the proper type</li>
 388             <li>if the value is not valid for the property</li>
 389             </ul>
 390             <p><em>Not every implementation can detect each condition</em></p>
 391
 392         @throws com::sun::star::lang::WrappedTargetException
 393             if an error occurs processing the event.
 394
 395         @see com::sun::star::configuration::backend::NodeAttribute
 396      */
 397     void setPropertyValue(  [in] any aValue )
 398             raises( MalformedDataException,
 399                     com::sun::star::lang::WrappedTargetException );
 400
 401     //-------------------------------------------------------------------------
 402
 403     /** receives notification that the value of the current localized property
 404         is overridden for a specific locale .
 405
 406         @param aValue
 407             specifies the new value of the property.
 408
 409             <p> The value must match the type of the current property.
 410                 If the property does not have the
 411                 <const>SchemaAttribute::REQUIRED</const> flag set,
 412                 the value can be <void/>.
 413             </p>
 414
 415         @param aLocale
 416             specifies the locale this value should apply to.
 417
 418         @throws com::sun::star::configuration::backend::MalformedDataException
 419             <ul>
 420             <li>if there isn't a property in progress currently</li>
 421             <li>if the current property isn't localized</li>
 422             <li>if there already was a change to the property for that locale</li>
 423             <li>if the value does not have the proper type</li>
 424             <li>if the value is not valid for the property</li>
 425             <li>if the locale is not a valid locale</li>
 426             </ul>
 427             <p><em>Not every implementation can detect each condition</em></p>
 428
 429         @throws com::sun::star::lang::WrappedTargetException
 430             if an error occurs processing the event.
 431
 432         @see com::sun::star::configuration::backend::NodeAttribute
 433      */
 434     void setPropertyValueForLocale([in] any aValue,
 435                                          [in] string aLocale )
 436             raises( MalformedDataException,
 437                     com::sun::star::lang::WrappedTargetException );
 438
 439     //-------------------------------------------------------------------------
 440
 441     /** receives notification that a property description is complete.
 442
 443         <p> Must match an open call to
 444             <member>XLayerHandler::overrideProperty()</member>,
 445         </p>
 446
 447         @throws com::sun::star::configuration::backend::MalformedDataException
 448             <ul>
 449             <li>if invalid data is detected in the property</li>
 450             <li>if no property is started at all</li>
 451             </ul>
 452             <p><em>Not every implementation can detect each condition</em></p>
 453
 454         @throws com::sun::star::lang::WrappedTargetException
 455             if an error occurs processing the event.
 456      */
 457     void endProperty(  )
 458             raises( MalformedDataException,
 459                     com::sun::star::lang::WrappedTargetException );
 460     //-------------------------------------------------------------------------
 461
 462     /** receives notification that a property having a <void/> value is added
 463         to the current node.
 464
 465         <p> The current node must be extensible.
 466         </p>
 467
 468         @param aName
 469             specifies the name of the new property.
 470
 471         @param aAttributes
 472             specifies the attributes of the new property.
 473
 474             <p> The value is a combination of
 475                 <type>NodeAttribute</type> flags and may also contain the
 476                 <const>SchemaAttribute::REQUIRED</const> flag.
 477             </p>
 478             <p> <const>NodeAttribute::MANDATORY</const> need not be set,
 479                 as dynamically added properties always are mandatory
 480                 in subsequent layers.
 481             </p>
 482
 483         @param aType
 484             specifies the type of the new property.
 485
 486         @throws com::sun::star::configuration::backend::MalformedDataException
 487             <ul>
 488             <li>if there isn't an extensible node in progress currently</li>
 489             <li>if a property with that name already exists</li>
 490             <li>if the specified type is not allowed for a property</li>
 491             <li>if the name is not a valid property name</li>
 492             <li><li>if the attributes are not valid for the property</li>
 493             </ul>
 494             <p><em>Not every implementation can detect each condition</em></p>
 495
 496         @throws com::sun::star::lang::WrappedTargetException
 497             if an error occurs processing the event.
 498
 499         @see com::sun::star::configuration::backend::SchemaAttribute
 500      */
 501     void addProperty(   [in] string aName,
 502                          [in] short aAttributes,
 503                         [in] type aType )
 504             raises( MalformedDataException,
 505                     com::sun::star::lang::WrappedTargetException );
 506
 507     //-------------------------------------------------------------------------
 508
 509     /** receives notification that a property having a non-<void/> value
 510         is added to the current node.
 511
 512         <p> The current node must be extensible.
 513         </p>
 514
 515         @param aName
 516             specifies the name of the new property.
 517
 518         @param aAttributes
 519             specifies the attributes of the new property.
 520
 521             <p> The value is a combination of
 522                 <type>NodeAttribute</type> flags and may also contain the
 523                 <const>SchemaAttribute::REQUIRED</const> flag.
 524             </p>
 525             </p>
 526             <p> <const>NodeAttribute::MANDATORY</const> need not be set,
 527                 as dynamic properties always are mandatory
 528                 in subsequent layers.
 529             </p>
 530
 531         @param aValue
 532             specifies the value of the new property.
 533
 534             <p> The value also determines the type.
 535                 Therefore the value must not be <void/>.
 536             </p>
 537
 538         @throws com::sun::star::configuration::backend::MalformedDataException
 539             <ul>
 540             <li>if there isn't an extensible node in progress currently</li>
 541             <li>if a property with that name already exists</li>
 542             <li>if the type of the value is not an allowed type
 543                 or if the value is <void/></li>
 544             <li>if the name is not a valid property name</li>
 545             <li>if the value is not valid for the property</li>
 546             <li>if the attributes are not valid for the property</li>
 547             </ul>
 548             <p><em>Not every implementation can detect each condition</em></p>
 549
 550         @throws com::sun::star::lang::WrappedTargetException
 551             if an error occurs processing the event.
 552
 553         @see com::sun::star::configuration::backend::SchemaAttribute
 554      */
 555     void addPropertyWithValue(  [in] string aName,
 556                                  [in] short aAttributes,
 557                                 [in] any aValue )
 558             raises( MalformedDataException,
 559                     com::sun::star::lang::WrappedTargetException );
 560
 561     //-------------------------------------------------------------------------
 562 };
 563
 564 //=============================================================================
 565
 566 }; }; }; }; };
 567
 568 //=============================================================================
 569
 570 #endif