offapi/com/sun/star/configuration/backend/XSchemaHandler.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: XSchemaHandler.idl,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_configuration_backend_XSchemaHandler_idl__
  31 #define __com_sun_star_configuration_backend_XSchemaHandler_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 schema as a sequence of events.
  56
  57     @since OOo 1.1.2
  58  */
  59 published interface XSchemaHandler: ::com::sun::star::uno::XInterface
  60 {
  61     //-------------------------------------------------------------------------
  62
  63     /** receives notification that a schema description is started.
  64
  65         <p> The schema descrption may comprise components templates or both.
  66         </p>
  67
  68         @throws com::sun::star::configuration::backend::MalformedDataException
  69             if a schema is already started (and has not been ended).
  70
  71         @throws com::sun::star::lang::WrappedTargetException
  72             if an error occurs processing the event.
  73      */
  74     void startSchema( )
  75             raises( MalformedDataException,
  76                     com::sun::star::lang::WrappedTargetException );
  77     //-------------------------------------------------------------------------
  78
  79     /** receives notification that the current schema description is complete.
  80
  81         <p> Must match a previous call to <member>startSchema</member>.
  82         </p>
  83
  84         @throws com::sun::star::configuration::backend::MalformedDataException
  85             <ul>
  86             <li>if invalid data is detected in the schema</li>
  87             <li>if there is a unfinished component or template in progress</li>
  88             <li>if no schema is started at all</li>
  89             </ul>
  90             <p><em>Not every implementation can detect each condition</em></p>
  91
  92         @throws com::sun::star::lang::WrappedTargetException
  93             if an error occurs processing the event.
  94      */
  95     void endSchema(  )
  96             raises( MalformedDataException,
  97                     com::sun::star::lang::WrappedTargetException );
  98     //-------------------------------------------------------------------------
  99
 100     /** receives notification that the schema depends on templates
 101         from a different component.
 102
 103         @param aName
 104             specifies the name of the component.
 105
 106         @throws com::sun::star::configuration::backend::MalformedDataException
 107             <ul>
 108             <li>if there is a unfinished component or template in progress</li>
 109             <li>if no schema is started at all</li>
 110             <li>if the name is not a valid component name</li>
 111             <li>if the requested component is not found</li>
 112             </ul>
 113             <p><em>Not every implementation can detect each condition</em></p>
 114
 115         @throws com::sun::star::lang::WrappedTargetException
 116             if an error occurs processing the event.
 117      */
 118     void importComponent( [in] string aName )
 119             raises( MalformedDataException,
 120                     com::sun::star::lang::WrappedTargetException );
 121     //-------------------------------------------------------------------------
 122
 123     /** receives notification that a component description is started.
 124
 125         <p> Subsequent calls describe the schema of the component
 126             until a matching call to <member>endComponent</member>
 127             is encountered.
 128         </p>
 129
 130         @param aName
 131             specifies the name of the component.
 132
 133         @throws com::sun::star::configuration::backend::MalformedDataException
 134             <ul>
 135             <li>if there is a unfinished component or template in progress </li>
 136             <li>if no schema is started at all </li>
 137             <li>if there already is a component data tree of this name</li>
 138             <li>if the name is not a valid component name</li>
 139             <li>if the instance supports no component schemas (only templates)</li>
 140             </ul>
 141             <p><em>Not every implementation can detect each condition</em></p>
 142
 143         @throws com::sun::star::lang::WrappedTargetException
 144             if an error occurs processing the event.
 145      */
 146     void startComponent( [in] string aName )
 147             raises( MalformedDataException,
 148                     com::sun::star::lang::WrappedTargetException );
 149     //-------------------------------------------------------------------------
 150
 151     /** receives notification that a component description is complete.
 152
 153         <p> Must match a previous call to <member>startComponent</member>.
 154         </p>
 155
 156         @throws com::sun::star::configuration::backend::MalformedDataException
 157             <ul>
 158             <li>if invalid data is detected in the component<li>
 159             <li>if there is a unfinished subnode in progress<li>
 160             <li>if no component has been started at all<li>
 161             <li>if the instance supports no component schemas (only templates)<li>
 162             </ul>
 163             <p><em>Not every implementation can detect each condition</em></p>
 164
 165         @throws com::sun::star::lang::WrappedTargetException
 166             if an error occurs processing the event.
 167      */
 168     void endComponent(  )
 169             raises( MalformedDataException,
 170                     com::sun::star::lang::WrappedTargetException );
 171     //-------------------------------------------------------------------------
 172
 173     /** receives notification that a template description is started for a group.
 174
 175         <p> Subsequent calls describe the members and properties of the template
 176             until a matching call to <member>endTemplate</member>
 177             is encountered.
 178         </p>
 179
 180         @param aTemplate
 181             specifies the identity of the template.
 182
 183         @param aAttributes
 184             specifies the attributes of the template.
 185
 186             <p> The value is a combination of
 187                 <type>SchemaAttribute</type> flags.
 188             </p>
 189             <p> <const>SchemaAttribute::EXTENSIBLE</const> can be used
 190                 to describe a template for a node with an extensible
 191                 set of properties.
 192             </p>
 193
 194         @throws com::sun::star::configuration::backend::MalformedDataException
 195             <ul>
 196             <li>if there is a unfinished component or template in progress</li>
 197             <li>if no schema is started at all </li>
 198             <li>if there already is a template with that identifier</li>
 199             <li>if the name is not a valid template identifier </li>
 200             <li>if the attributes are not valid for a group</li>
 201             <li>if the instance supports no templates (only component schemas)</li>
 202             </ul>
 203             <p><em>Not every implementation can detect each condition</em></p>
 204
 205         @throws com::sun::star::lang::WrappedTargetException
 206             if an error occurs processing the event.
 207
 208         @see com::sun::star::configuration::backend::SchemaAttribute
 209      */
 210     void startGroupTemplate( [in] TemplateIdentifier aTemplate,
 211                              [in] short  aAttributes  )
 212             raises( MalformedDataException,
 213                     com::sun::star::lang::WrappedTargetException );
 214     //-------------------------------------------------------------------------
 215
 216     /** receives notification that a template description is started for a set.
 217
 218         <p> Subsequent calls describe the members and properties of the template
 219             until a matching call to <member>endTemplate</member>
 220             is encountered.
 221         </p>
 222
 223         @param aTemplate
 224             specifies the identity of the template.
 225
 226         @param aAttributes
 227             specifies the attributes of the template.
 228
 229             <p> The value is a combination of
 230                 <type>SchemaAttribute</type> flags.
 231             </p>
 232             <p> <const>SchemaAttribute::EXTENSIBLE</const> can be used
 233                 to describe a template for a node with an extensible
 234                 set of properties.
 235             </p>
 236
 237         @param aItemType
 238             specifies the (default) template for set items.
 239
 240         @throws com::sun::star::configuration::backend::MalformedDataException
 241             <ul>
 242             <li>if there is a unfinished component or template in progress</li>
 243             <li>if no schema is started at all </li>
 244             <li>if there already is a template with that identifier</li>
 245             <li>if the item-type template is not found</li>
 246             <li>if the name or item-type are not valid template identifiers </li>
 247             <li>if the attributes are not valid for a set</li>
 248             <li>if the instance supports no templates (only component schemas).</li>
 249             </ul>
 250             <p><em>Not every implementation can detect each condition</em></p>
 251
 252         @throws com::sun::star::lang::WrappedTargetException
 253             if an error occurs processing the event.
 254
 255         @see com::sun::star::configuration::backend::SchemaAttribute
 256      */
 257     void startSetTemplate(      [in] TemplateIdentifier aTemplate,
 258                             [in] short  aAttributes,
 259                             [in] TemplateIdentifier aItemType  )
 260             raises( MalformedDataException,
 261                     com::sun::star::lang::WrappedTargetException );
 262     //-------------------------------------------------------------------------
 263
 264     /** receives notification that a template description is complete.
 265
 266         <p> Must match a previous call to <member>startGroupTemplate</member>
 267             or <member>startSetTemplate</member>.
 268         </p>
 269
 270         @throws com::sun::star::configuration::backend::MalformedDataException
 271             <ul>
 272             <li>if invalid data is detected in the template</li>
 273             <li>if there is a unfinished subnode in progress</li>
 274             <li>if no template has been started at all</li>
 275             <li>if the instance supports no templates (only component schemas)</li>
 276             </ul>
 277             <p><em>Not every implementation can detect each condition</em></p>
 278
 279         @throws com::sun::star::lang::WrappedTargetException
 280             if an error occurs processing the event.
 281      */
 282     void endTemplate(  )
 283             raises( MalformedDataException,
 284                     com::sun::star::lang::WrappedTargetException );
 285     //-------------------------------------------------------------------------
 286
 287     /** receives notification that a group description is started.
 288
 289         <p> Subsequent calls describe the members and properties of the group
 290             until a matching call to <member>endNode</member>
 291             is encountered.
 292         </p>
 293
 294         @param aName
 295             specifies the name of the group.
 296
 297         @param aAttributes
 298             specifies the attributes of the node.
 299
 300             <p> The value is a combination of
 301                 <type>SchemaAttribute</type> flags.
 302             </p>
 303             <p> <const>SchemaAttribute::EXTENSIBLE</const> can be used
 304                 to describe a group with an extensible set of properties.
 305             </p>
 306
 307         @throws com::sun::star::configuration::backend::MalformedDataException
 308             <ul>
 309             <li>if there isn't a group node in progress currently</li>
 310             <li>if there already is a node with that name</li>
 311             <li>if the name is not a valid node name</li>
 312             <li>if the attributes are not valid for a group</li>
 313             </ul>
 314             <p><em>Not every implementation can detect each condition</em></p>
 315
 316         @throws com::sun::star::lang::WrappedTargetException
 317             if an error occurs processing the event.
 318
 319         @see com::sun::star::configuration::backend::SchemaAttribute
 320      */
 321     void startGroup( [in] string aName,
 322                      [in] short  aAttributes )
 323             raises( MalformedDataException,
 324                     com::sun::star::lang::WrappedTargetException );
 325     //-------------------------------------------------------------------------
 326
 327     /** receives notification that a set description is started.
 328
 329         <p> Subsequent calls describe the item-types and properties of the set
 330             until a matching call to <member>endNode</member>
 331             is encountered.
 332         </p>
 333
 334         @param aName
 335             specifies the name of the set.
 336
 337         @param aAttributes
 338             specifies the attributes of the node.
 339
 340             <p> The value is a combination of
 341                 <type>SchemaAttribute</type> flags.
 342             </p>
 343             <p> <const>SchemaAttribute::EXTENSIBLE</const> can be used
 344                 to describe a set with an extensible set of properties.
 345             </p>
 346
 347         @param aItemType
 348             specifies the (default) template for set items.
 349
 350         @throws com::sun::star::configuration::backend::MalformedDataException
 351             <ul>
 352             <li>if there isn't a group node in progress currently</li>
 353             <li>if there already is a node with that name</li>
 354             <li>if the item-type template is not found</li>
 355             <li>if the name is not a valid node name</li>
 356             <li>if the item-type is not a valid template identifier</li>
 357             <li>if the attributes are not valid for a set</li>
 358             </ul>
 359             <p><em>Not every implementation can detect each condition</em></p>
 360
 361         @throws com::sun::star::lang::WrappedTargetException
 362             if an error occurs processing the event.
 363
 364         @see com::sun::star::configuration::backend::SchemaAttribute
 365      */
 366     void startSet( [in] string aName,
 367                    [in] short  aAttributes,
 368                    [in] TemplateIdentifier aItemType )
 369             raises( MalformedDataException,
 370                     com::sun::star::lang::WrappedTargetException );
 371     //-------------------------------------------------------------------------
 372
 373     /** receives notification that a node description is complete.
 374
 375         <p> Must match the last open call to <member>startGroup</member>
 376             or <member>startSet</member>.
 377         </p>
 378
 379         @throws com::sun::star::configuration::backend::MalformedDataException
 380             <ul>
 381             <li>if the name is not a the name of the node in progress</li>
 382             <li>if invalid data is detected in the node</li>
 383             <li>if no node has been started at all</li>
 384             </ul>
 385             <p><em>Not every implementation can detect each condition</em></p>
 386
 387         @throws com::sun::star::lang::WrappedTargetException
 388             if an error occurs processing the event.
 389      */
 390     void endNode(  )
 391             raises( MalformedDataException,
 392                     com::sun::star::lang::WrappedTargetException );
 393     //-------------------------------------------------------------------------
 394
 395     /** receives notification that a property is added to the current node.
 396
 397         <p>     The property will have a default value of <NULL/>
 398             (unless it is <const>SchemaAttribute::REQUIRED</const>).
 399         </p>
 400
 401         @param aName
 402             specifies the name of the new property.
 403
 404         @param aAttributes
 405             specifies the attributes of the new property.
 406
 407             <p> The value is a combination of
 408                 <type>SchemaAttribute</type> flags.
 409             </p>
 410
 411         @param aType
 412             specifies the type of the new property.
 413
 414         @throws com::sun::star::configuration::backend::MalformedDataException
 415             <ul>
 416             <li>if there isn't a group or extensible node in progress currently</li>
 417             <li>if a property with the same name already exists</li>
 418             <li>if the specified type is not allowed</li>
 419             <li>if the name is not a valid property name</li>
 420             <li>if the attributes are not valid for a property</li>
 421             </ul>
 422             <p><em>Not every implementation can detect each condition</em></p>
 423
 424         @throws com::sun::star::lang::WrappedTargetException
 425             if an error occurs processing the event.
 426
 427         @see com::sun::star::configuration::backend::SchemaAttribute
 428      */
 429     void addProperty( [in] string aName,
 430                        [in] short aAttributes,
 431                       [in] type aType )
 432             raises( MalformedDataException,
 433                     com::sun::star::lang::WrappedTargetException );
 434
 435     //-------------------------------------------------------------------------
 436
 437     /** receives notification that a property having a default value
 438         is added to the current node.
 439
 440         @param aName
 441             specifies the name of the new property.
 442
 443         @param aAttributes
 444             specifies the attributes of the new property.
 445
 446             <p> The value is a combination of
 447                 <type>SchemaAttribute</type> flags.
 448             </p>
 449
 450         @param aDefaultValue
 451             specifies the value of the new property.
 452
 453             <p> The value also determines the type.
 454                 Therefore the value must not be <void/>.
 455             </p>
 456
 457         @throws com::sun::star::configuration::backend::MalformedDataException
 458             <ul>
 459             <li>if there isn't a group or extensible node in progress currently</li>
 460             <li>if a property with the same name already exists</li>
 461             <li>if the type of the default value is not an allowed type,
 462                 or if the default value is <void/></li>
 463             <li>if the name is not a valid property name</li>
 464             <li>if the attributes are not valid for a property</li>
 465             </ul>
 466             <p><em>Not every implementation can detect each condition</em></p>
 467
 468         @throws com::sun::star::lang::WrappedTargetException
 469             if an error occurs processing the event.
 470
 471         @see com::sun::star::configuration::backend::SchemaAttribute
 472      */
 473     void addPropertyWithDefault( [in] string aName,
 474                                   [in] short aAttributes,
 475                                  [in] any aDefaultValue )
 476             raises( MalformedDataException,
 477                     com::sun::star::lang::WrappedTargetException );
 478
 479     //-------------------------------------------------------------------------
 480
 481     /** receives notification that the current group has a child node
 482         that is an instance of a specified template.
 483
 484         @param aName
 485             specifies the name of the new node.
 486
 487         @param aTemplate
 488             specifies a template that describes the new node.
 489
 490         @throws com::sun::star::configuration::backend::MalformedDataException
 491             <ul>
 492             <li>if there isn't a group node in progress currently</li>
 493             <li>if there already is a node with that name</li>
 494             <li>if the template is not found</li>
 495             <li>if the name or template name are not valid</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     void addInstance( [in] string aName,
 503                        [in] TemplateIdentifier aTemplate )
 504             raises( MalformedDataException,
 505                     com::sun::star::lang::WrappedTargetException );
 506
 507     //-------------------------------------------------------------------------
 508
 509     /** receives notification that the current set can contain items
 510         that are instances of a specified template.
 511
 512         @param aItemType
 513             specifies a template that is accepted as valid item type
 514             for the current set node.
 515
 516         @throws com::sun::star::configuration::backend::MalformedDataException
 517             <ul>
 518             <li>if there isn't a set node in progress currently</li>
 519             <li>if the template is not found</li>
 520             <li>if the name is not a valid template name</li>
 521             </ul>
 522             <p><em>Not every implementation can detect each condition</em></p>
 523
 524         @throws com::sun::star::lang::WrappedTargetException
 525             if an error occurs processing the event.
 526      */
 527     void addItemType( [in] TemplateIdentifier aItemType )
 528             raises( MalformedDataException,
 529                     com::sun::star::lang::WrappedTargetException );
 530
 531     //-------------------------------------------------------------------------
 532
 533 };
 534
 535 //=============================================================================
 536
 537 }; }; }; }; };
 538
 539 //=============================================================================
 540
 541 #endif