offapi/com/sun/star/configuration/backend/XUpdateHandler.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: XUpdateHandler.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_XUpdateHandler_idl__
  31 #define __com_sun_star_configuration_backend_XUpdateHandler_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 #ifndef __com_sun_star_lang_IllegalAccessException_idl__
  50 #include <com/sun/star/lang/IllegalAccessException.idl>
  51 #endif
  52
  53 //=============================================================================
  54
  55 module com { module sun { module star { module configuration { module backend {
  56
  57 //=============================================================================
  58
  59 /** receives a description of a configuration update or layer
  60     as a sequence of events.
  61
  62     @since OOo 1.1.2
  63  */
  64 published interface XUpdateHandler: ::com::sun::star::uno::XInterface
  65 {
  66     //-------------------------------------------------------------------------
  67
  68     /** receives notification that a update or description is started.
  69
  70         @throws com::sun::star::configuration::backend::MalformedDataException
  71             if the update already was started
  72
  73         @throws com::sun::star::lang::IllegalAccessException
  74             if the target layer is read-only
  75             <p><em>Some implementations can only detect this when executing
  76                 <member>XUpdateHandler::endUpdate()</member></em>
  77             </p>
  78
  79         @throws com::sun::star::lang::WrappedTargetException
  80             if an error occurs processing the event.
  81      */
  82     void startUpdate(  )
  83             raises( MalformedDataException,
  84                     com::sun::star::lang::IllegalAccessException,
  85                     com::sun::star::lang::WrappedTargetException );
  86     //-------------------------------------------------------------------------
  87
  88     /** receives notification that the current update description is complete.
  89
  90         <p> Must match a previous call to <member>XUpdateHandler::startUpdate()</member>.
  91         </p>
  92
  93         @throws com::sun::star::configuration::backend::MalformedDataException
  94             <ul>
  95             <li>if no update is started at all</li>
  96             <li>if invalid data is detected in the update</li>
  97             <li>if there is an unfinished subnode in progress</li>
  98             <li>if the update tries to change read-only data</li>
  99             </ul>
 100             <p><em>Not every implementation can detect each condition</em></p>
 101
 102         @throws com::sun::star::lang::IllegalAccessException
 103             if the target layer is read-only
 104
 105         @throws com::sun::star::lang::WrappedTargetException
 106             if an error occurs processing the event.
 107      */
 108     void endUpdate(  )
 109             raises( MalformedDataException,
 110                     com::sun::star::lang::IllegalAccessException,
 111                     com::sun::star::lang::WrappedTargetException );
 112     //-------------------------------------------------------------------------
 113
 114     /** receives notification that a modification of a node is started.
 115
 116         <p> Subsequent calls describe changes to properties and items or
 117             members of the node until a matching call to
 118             <member>XUpdateHandler::endNode()</member> is encountered.
 119         </p>
 120
 121         @param aName
 122             specifies the name of the node.
 123
 124         @param aAttributes
 125             specifies attribute values to be applied to the node in the
 126             current layer.
 127
 128             <p> The value is a combination of
 129                 <type>NodeAttribute</type> flags.
 130             </p>
 131             <p> Only attributes which are selected in aAttributeMask
 132                 are changed.
 133             </p>
 134
 135         @param aAttributeMask
 136             specifies which attributes should be changed for the node.
 137
 138             <p> The value is a combination of
 139                 <type>NodeAttribute</type> flags.
 140             </p>
 141
 142         @param bReset
 143             if <TRUE/>, specifies that the node should be reset to its default
 144             state as given by lower layers and the schema or template prior
 145             to applying the changes.
 146
 147         @throws com::sun::star::configuration::backend::MalformedDataException
 148             <ul>
 149             <li>if there isn't an update in progress at all</li>
 150             <li>if a node is not valid in this place</li>
 151             <li>if there already was a change to that node</li>
 152             <li>if there is no node with that name</li>
 153             <li>if the node is read-only</li>
 154             <li>if the name is not a valid node name</li>
 155             <li>if the attributes or mask are not valid for the node</li>
 156             </ul>
 157             <p><em>Not every implementation can detect each condition</em></p>
 158
 159         @throws com::sun::star::lang::WrappedTargetException
 160             if an error occurs processing the event.
 161
 162         @see com::sun::star::configuration::backend::NodeAttribute
 163      */
 164     void modifyNode ( [in] string aName,
 165                       [in] short  aAttributes,
 166                       [in] short  aAttributeMask,
 167                       [in] boolean bReset )
 168             raises( MalformedDataException,
 169                     com::sun::star::lang::WrappedTargetException );
 170     //-------------------------------------------------------------------------
 171
 172     /** receives notification that a node is started as a new item.
 173
 174         <p> The current node must be a set and
 175             a preexisting item (if any) must be removeable.
 176         </p>
 177         <p> The new item will be created from the default template
 178             of the set.
 179         </p>
 180         <p> Subsequent calls describe the difference from the template
 181             of properties, items or members of the node until a matching call
 182             to <member>XUpdateHandler::endNode()</member> is encountered.
 183         </p>
 184
 185         @param aName
 186             specifies the name of the new item.
 187
 188         @param aAttributes
 189             specifies attribute values to be applied to the new node.
 190
 191             <p> The value is a combination of
 192                 <type>NodeAttribute</type> flags.  Note that
 193                 <member>NodeAttribute::FUSE</member> has an impact on the
 194                 semantics of this method.
 195             </p>
 196
 197         @throws com::sun::star::configuration::backend::MalformedDataException
 198             <ul>
 199             <li>if there isn't a set node in progress currently</li>
 200             <li>if there already was a change to an item of that name</li>
 201             <li>if the template for the new node is not found</li>
 202             <li>if an item of that name exists and is not removeable</li>
 203             <li>if the name is not a valid item name</li>
 204             <li>if the attributes are not valid for the node</li>
 205             </ul>
 206             <p><em>Not every implementation can detect each condition</em></p>
 207
 208         @throws com::sun::star::lang::WrappedTargetException
 209             if an error occurs processing the event.
 210
 211         @see com::sun::star::configuration::backend::NodeAttribute
 212      */
 213     void addOrReplaceNode (     [in] string aName,
 214                             [in] short  aAttributes )
 215             raises( MalformedDataException,
 216                     com::sun::star::lang::WrappedTargetException );
 217     //-------------------------------------------------------------------------
 218
 219     /** receives notification that a node is started as a new item
 220         based on a particular template.
 221
 222         <p> The current node must be a set and
 223             a preexisting item (if any) must be removeable.
 224         </p>
 225         <p> Subsequent calls describe the difference from the template
 226             of properties or members of the node until a matching call
 227             to <member>XUpdateHandler::endNode()</member> is encountered.
 228         </p>
 229
 230         @param aName
 231             specifies the name of the item.
 232
 233         @param aTemplate
 234             specifies the template to use for the new node
 235
 236         @param aAttributes
 237             specifies attribute values to be applied to the new node.
 238
 239             <p> The value is a combination of
 240                 <type>NodeAttribute</type> flags.  Note that
 241                 <member>NodeAttribute::FUSE</member> has an impact on the
 242                 semantics of this method.
 243             </p>
 244
 245         @throws com::sun::star::configuration::backend::MalformedDataException
 246             <ul>
 247             <li>if there isn't a set node in progress currently</li>
 248             <li>if there already was a change to an item of that name</li>
 249             <li>if the template for the new node is not found</li>
 250             <li>if an item of that name exists and is not removeable</li>
 251             <li>if the name is not a valid item name</li>
 252             <li>if the template is not a valid item type for the containing set</li>
 253             <li>if the attributes are not valid for the node</li>
 254             </ul>
 255             <p><em>Not every implementation can detect each condition</em></p>
 256
 257         @throws com::sun::star::lang::WrappedTargetException
 258             if an error occurs processing the event.
 259
 260         @see com::sun::star::configuration::backend::NodeAttribute
 261      */
 262     void addOrReplaceNodeFromTemplate(  [in] string aName,
 263                                         [in] short  aAttributes,
 264                                         [in] TemplateIdentifier aTemplate )
 265             raises( MalformedDataException,
 266                     com::sun::star::lang::WrappedTargetException );
 267     //-------------------------------------------------------------------------
 268
 269     /** receives notification that a node modification is complete.
 270
 271         <p> Must match the last open call to
 272             <member>XUpdateHandler::modifyNode()</member>,
 273             <member>XUpdateHandler::addOrReplaceNode()</member> or
 274             <member>XUpdateHandler::addOrReplaceNodeFromTemplate()</member>.
 275         </p>
 276
 277         @throws com::sun::star::configuration::backend::MalformedDataException
 278             <ul>
 279             <li>if invalid data is detected in the node</li>
 280             <li>if no node is started at all</li>
 281             </ul>
 282             <p><em>Not every implementation can detect each condition</em></p>
 283
 284         @throws com::sun::star::lang::WrappedTargetException
 285             if an error occurs processing the event.
 286      */
 287     void endNode( )
 288             raises( MalformedDataException,
 289                     com::sun::star::lang::WrappedTargetException );
 290     //-------------------------------------------------------------------------
 291
 292     /** receives notification that an item is to be dropped from a set.
 293
 294         <p> The current node must be a set and
 295             the item must be removeable.
 296         </p>
 297
 298         @param aName
 299             specifies the name of the node.
 300
 301         @throws com::sun::star::configuration::backend::MalformedDataException
 302             <ul>
 303             <li>if there isn't a set node in progress currently</li>
 304             <li>if there already was a change to a node of that name</li>
 305             <li>if there is no item with that name</li>
 306             <li>if the item is not removeable</li>
 307             <li>if the name is not a valid node name</li>
 308             </ul>
 309             <p><em>Not every implementation can detect each condition</em></p>
 310
 311         @throws com::sun::star::lang::WrappedTargetException
 312             if an error occurs processing the event.
 313      */
 314     void removeNode( [in] string aName )
 315             raises( MalformedDataException,
 316                     com::sun::star::lang::WrappedTargetException );
 317     //-------------------------------------------------------------------------
 318
 319     /** receives notification that modification of an existing property is started. .
 320
 321         <p> Subsequent calls describe changes to the value(s)
 322             of the property until a matching call to
 323             <member>XUpdateHandler::endProperty()</member> is encountered.
 324         </p>
 325
 326         @param aName
 327             specifies the name of the property.
 328
 329         @param aAttributes
 330             specifies new attributes of the property.
 331
 332             <p> The value is a combination of
 333                 <type>NodeAttribute</type> flags.
 334             </p>
 335             <p> Only attributes which are selected in aAttributeMask are changed.
 336             </p>
 337             <p> <const>NodeAttribute::MANDATORY</const> need not be set
 338                 and can't be removed, as dynamic properties always are mandatory
 339                 in subsequent layers.
 340             </p>
 341
 342         @param aAttributeMask
 343             specifies which attributes should be changed for the property.
 344
 345             <p> The value is a combination of
 346                 <type>NodeAttribute</type> flags.
 347             </p>
 348
 349         @param aType
 350             specifies the type of the property.
 351
 352             <p> A <void/> type can be used to signify that
 353                 the type is unknown and should not be recorded.
 354             </p>
 355
 356         @throws com::sun::star::configuration::backend::MalformedDataException
 357             <ul>
 358             <li>if there isn't a group or extensible node in progress currently</li>
 359             <li>if there already was a change to a property of that name</li>
 360             <li>if there is no property with that name</li>
 361             <li>if the property is read-only</li>
 362             <li>if the name is not a valid property name</li>
 363             <li>if the attributes are not valid for the property</li>
 364             </ul>
 365             <p><em>Not every implementation can detect each condition</em></p>
 366
 367         @throws com::sun::star::lang::WrappedTargetException
 368             if an error occurs processing the event.
 369
 370         @see com::sun::star::configuration::backend::NodeAttribute
 371      */
 372     void modifyProperty( [in] string aName,
 373                           [in] short aAttributes,
 374                           [in] short aAttributeMask,
 375                          [in] type aType )
 376             raises( MalformedDataException,
 377                     com::sun::star::lang::WrappedTargetException );
 378     //-------------------------------------------------------------------------
 379
 380     /** receives notification about a change to the value of
 381         the current property.
 382
 383         @param aValue
 384             specifies the new value of the property.
 385
 386             <p> The value must match the type of the existing property.
 387                 If the property does not have the
 388                 <const>SchemaAttribute::REQUIRED</const> flag set,
 389                 the value can be <void/>.
 390             </p>
 391
 392         @throws com::sun::star::configuration::backend::MalformedDataException
 393             <ul>
 394             <li>if there isn't a property modification in progress currently</li>
 395             <li>if there already was a change to this value</li>
 396             <li>if the type of the value is not an allowed type</li>
 397             <li>if the value is not valid for the property</li>
 398             </ul>
 399             <p><em>Not every implementation can detect each condition</em></p>
 400
 401         @throws com::sun::star::lang::WrappedTargetException
 402             if an error occurs processing the event.
 403
 404         @see com::sun::star::configuration::backend::NodeAttribute
 405      */
 406     void setPropertyValue( [in] any aValue )
 407             raises( MalformedDataException,
 408                     com::sun::star::lang::WrappedTargetException );
 409     //-------------------------------------------------------------------------
 410
 411     /** receives notification about a change to the value of
 412         the current property for a specific locale.
 413
 414         @param aValue
 415             specifies the new value of the property for the given locale.
 416
 417             <p> The value must match the type of the existing property.
 418                 If the property does not have the
 419                 <const>SchemaAttribute::REQUIRED</const> flag set,
 420                 the value can be <void/>.
 421             </p>
 422
 423         @param aLocale
 424             specifies the locale that the new value applies to.
 425
 426         @throws com::sun::star::configuration::backend::MalformedDataException
 427             <ul>
 428             <li>if there isn't a property modification in progress currently</li>
 429             <li>if the property is not localizable</li>
 430             <li>if there already was a change to this value</li>
 431             <li>if the type of the value is not an allowed type</li>
 432             <li>if the value is not valid for the property</li>
 433             <li>if the locale is not a valid locale name</li>
 434             </ul>
 435             <p><em>Not every implementation can detect each condition</em></p>
 436
 437         @throws com::sun::star::lang::WrappedTargetException
 438             if an error occurs processing the event.
 439
 440         @see com::sun::star::configuration::backend::NodeAttribute
 441      */
 442     void setPropertyValueForLocale( [in] any aValue, [in] string aLocale )
 443             raises( MalformedDataException,
 444                     com::sun::star::lang::WrappedTargetException );
 445     //-------------------------------------------------------------------------
 446
 447     /** receives notification that the value of the current property
 448         should be reset to its default.
 449
 450         @throws com::sun::star::configuration::backend::MalformedDataException
 451             <ul>
 452             <li>if there isn't a property modification in progress currently</li>
 453             <li>if there already was a change to this value</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         @see com::sun::star::configuration::backend::NodeAttribute
 461      */
 462     void resetPropertyValue( )
 463             raises( MalformedDataException,
 464                     com::sun::star::lang::WrappedTargetException );
 465     //-------------------------------------------------------------------------
 466
 467     /** receives notification that the value of the current property
 468         for a specific locale should be reset to its default.
 469
 470         @param aLocale
 471             specifies the locale the change applies to.
 472
 473         @throws com::sun::star::configuration::backend::MalformedDataException
 474             <ul>
 475             <li>if there isn't a property modification in progress currently</li>
 476             <li>if the property is not localizable</li>
 477             <li>if there already was a change to this value</li>
 478             <li>if the locale is not a valid locale name</li>
 479             </ul>
 480             <p><em>Not every implementation can detect each condition</em></p>
 481
 482         @throws com::sun::star::lang::WrappedTargetException
 483             if an error occurs processing the event.
 484
 485         @see com::sun::star::configuration::backend::NodeAttribute
 486      */
 487     void resetPropertyValueForLocale( [in] string aLocale )
 488             raises( MalformedDataException,
 489                     com::sun::star::lang::WrappedTargetException );
 490     //-------------------------------------------------------------------------
 491
 492     /** receives notification that a property modification is complete.
 493
 494         <p> Must match the last open call to
 495             <member>XUpdateHandler::modifyProperty()</member>.
 496         </p>
 497
 498         @throws com::sun::star::configuration::backend::MalformedDataException
 499             <ul>
 500             <li>if invalid data is detected in the property</li>
 501             <li>if no property is started at all</li>
 502             </ul>
 503             <p><em>Not every implementation can detect each condition</em></p>
 504
 505         @throws com::sun::star::lang::WrappedTargetException
 506             if an error occurs processing the event.
 507      */
 508     void endProperty( )
 509             raises( MalformedDataException,
 510                     com::sun::star::lang::WrappedTargetException );
 511     //-------------------------------------------------------------------------
 512
 513     /** receives notification that a property is reset to its default state.
 514
 515         @param aName
 516             specifies the name of the property.
 517
 518         @throws com::sun::star::configuration::backend::MalformedDataException
 519             <ul>
 520             <li>if there isn't a group or extensible node in progress currently</li>
 521             <li>if there already was a change to a property of that name</li>
 522             <li>if there is no property with that name, or if the property
 523                 has no default</li>
 524             <li>if the property is read-only</li>
 525             <li>if the name is not a valid property name</li>
 526             </ul>
 527             <p><em>Not every implementation can detect each condition</em></p>
 528
 529         @throws com::sun::star::lang::WrappedTargetException
 530             if an error occurs processing the event.
 531
 532         @see com::sun::star::configuration::backend::NodeAttribute
 533      */
 534     void resetProperty( [in] string aName )
 535             raises( MalformedDataException,
 536                     com::sun::star::lang::WrappedTargetException );
 537     //-------------------------------------------------------------------------
 538
 539     /** receives notification that a property having a value of <void/>
 540         is added to the current node.
 541
 542         <p> The current node must be extensible and
 543             a preexisting property (if any) must be
 544             removeable in this layer.
 545         </p>
 546
 547         @param aName
 548             specifies the name of the new property.
 549
 550         @param aAttributes
 551             specifies the attributes of the new property.
 552
 553             <p> The value is a combination of
 554                 <type>NodeAttribute</type> flags and may also contain the
 555                 <const>SchemaAttribute::REQUIRED</const> flag.
 556             </p>
 557             </p>
 558             <p> <const>NodeAttribute::MANDATORY</const> need not be set,
 559                 as dynamic properties always are mandatory
 560                 in subsequent layers.
 561             </p>
 562
 563         @param aType
 564             specifies the type of the new property.
 565
 566         @throws com::sun::star::configuration::backend::MalformedDataException
 567             <ul>
 568             <li>if there isn't a group or extensible node in progress currently</li>
 569             <li>if there already was a change to a property of that name</li>
 570             <li>if a property of that name exists and is not removeable</li>
 571             <li>if the specified type is not allowed</li>
 572             <li>if the name is not a valid property name</li>
 573             <li>if the attributes are not valid for the property</li>
 574             </ul>
 575             <p><em>Not every implementation can detect each condition</em></p>
 576
 577         @throws com::sun::star::lang::WrappedTargetException
 578             if an error occurs processing the event.
 579
 580         @see com::sun::star::configuration::backend::SchemaAttribute
 581      */
 582     void addOrReplaceProperty( [in] string aName,
 583                                 [in] short aAttributes,
 584                                [in] type aType )
 585             raises( MalformedDataException,
 586                     com::sun::star::lang::WrappedTargetException );
 587     //-------------------------------------------------------------------------
 588
 589     /** receives notification that a property having a non-<NULL/> value
 590         is added to the current node.
 591
 592         <p> The current node must be extensible and
 593             a preexisting property (if any) must be
 594             removeable in this layer.
 595         </p>
 596
 597         @param aName
 598             specifies the name of the new property.
 599
 600         @param aAttributes
 601             specifies the attributes of the new property.
 602
 603             <p> The value is a combination of
 604                 <type>NodeAttribute</type> flags and may also contain the
 605                 <const>SchemaAttribute::REQUIRED</const> flag.
 606             </p>
 607             </p>
 608             <p> <const>NodeAttribute::MANDATORY</const> need not be set,
 609                 as dynamic properties always are mandatory
 610                 in subsequent layers.
 611             </p>
 612
 613         @param aValue
 614             specifies the value of the new property.
 615
 616             <p> The value also determines the type.
 617                 Therefore the value must not be <void/>.
 618             </p>
 619
 620         @throws com::sun::star::configuration::backend::MalformedDataException
 621             <ul>
 622             <li>if there isn't a group or extensible node in progress currently</li>
 623             <li>if there already was a change to a property of that name</li>
 624             <li>if a property of that name exists and is not removeable</li>
 625             <li>if the type of the value is not an allowed type,
 626                 or if the value is <void/></li>
 627             <li>if the name is not a valid property name</li>
 628             <li>if the attributes are not valid for the property</li>
 629             </ul>
 630             <p><em>Not every implementation can detect each condition</em></p>
 631
 632         @throws com::sun::star::lang::WrappedTargetException
 633             if an error occurs processing the event.
 634
 635         @see com::sun::star::configuration::backend::SchemaAttribute
 636      */
 637     void addOrReplacePropertyWithValue( [in] string aName,
 638                                          [in] short aAttributes,
 639                                         [in] any aValue )
 640             raises( MalformedDataException,
 641                     com::sun::star::lang::WrappedTargetException );
 642     //-------------------------------------------------------------------------
 643
 644     /** receives notification that a property is dropped from the current node.
 645
 646         <p>The current node must be extensible and the property removeable.</p>
 647
 648         @param aName
 649             specifies the name of the property.
 650
 651         @throws com::sun::star::configuration::backend::MalformedDataException
 652             <ul>
 653             <li>if there isn't a group or extensible node in progress currently</li>
 654             <li>if there is no property with that name</li>
 655             <li>if the property is not removeable</li>
 656             <li>if the name is not a valid node name</li>
 657             </ul>
 658             <p><em>Not every implementation can detect each condition</em></p>
 659
 660         @throws com::sun::star::lang::WrappedTargetException
 661             if an error occurs processing the event.
 662      */
 663     void removeProperty( [in] string aName )
 664             raises( MalformedDataException,
 665                     com::sun::star::lang::WrappedTargetException );
 666     //-------------------------------------------------------------------------
 667
 668 };
 669
 670 //=============================================================================
 671
 672 }; }; }; }; };
 673
 674 //=============================================================================
 675
 676 #endif