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