offapi/com/sun/star/rdf/XDocumentMetadataAccess.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
  28 #ifndef __com_sun_star_rdf_XDocumentMetadataAccess_idl__
  29 #define __com_sun_star_rdf_XDocumentMetadataAccess_idl__
  30
  31 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  32 #include <com/sun/star/lang/IllegalArgumentException.idl>
  33 #endif
  34
  35 #ifndef __com_sun_star_lang_WrappedTargetException_idl__
  36 #include <com/sun/star/lang/WrappedTargetException.idl>
  37 #endif
  38
  39 #ifndef __com_sun_star_beans_PropertyValue_idl__
  40 #include <com/sun/star/beans/PropertyValue.idl>
  41 #endif
  42
  43 #ifndef __com_sun_star_container_ElementExistException_idl__
  44 #include <com/sun/star/container/ElementExistException.idl>
  45 #endif
  46
  47 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  48 #include <com/sun/star/container/NoSuchElementException.idl>
  49 #endif
  50
  51 #ifndef __com_sun_star_io_IOException_idl__
  52 #include <com/sun/star/io/IOException.idl>
  53 #endif
  54
  55 #ifndef __com_sun_star_io_XInputStream_idl__
  56 #include <com/sun/star/io/XInputStream.idl>
  57 #endif
  58
  59 #ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__
  60 #include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
  61 #endif
  62
  63 #ifndef __com_sun_star_embed_XStorage_idl__
  64 #include <com/sun/star/embed/XStorage.idl>
  65 #endif
  66
  67 #ifndef __com_sun_star_task_XInteractionHandler_idl__
  68 #include <com/sun/star/task/XInteractionHandler.idl>
  69 #endif
  70
  71 #ifndef __com_sun_star_rdf_FileFormat_idl__
  72 #include <com/sun/star/rdf/FileFormat.idl>
  73 #endif
  74
  75 #ifndef __com_sun_star_rdf_ParseException_idl__
  76 #include <com/sun/star/rdf/ParseException.idl>
  77 #endif
  78
  79 #ifndef __com_sun_star_rdf_XURI_idl__
  80 #include <com/sun/star/rdf/XURI.idl>
  81 #endif
  82
  83 #ifndef __com_sun_star_rdf_XMetadatable_idl__
  84 #include <com/sun/star/rdf/XMetadatable.idl>
  85 #endif
  86
  87 #ifndef __com_sun_star_rdf_XRepositorySupplier_idl__
  88 #include <com/sun/star/rdf/XRepositorySupplier.idl>
  89 #endif
  90
  91
  92 //=============================================================================
  93
  94 module com {   module sun {   module star {   module rdf {
  95
  96 //=============================================================================
  97 /** document metadata functionality related to the "manifest.rdf".
  98
  99     <p>
 100     This interface contains some methods that create connections between
 101     the content and the RDF metadata of an ODF document.
 102     The main idea is to make querying and manipulating the
 103     data in the metadata manifest easier.
 104     </p>
 105
 106     <p>
 107     Note that this interface inherits from <type>XURI</type>: the
 108     base URI of the document is the string value of the RDF node.
 109     This is so that you can easily make RDF statements about the document.
 110     </p>
 111
 112     @since OOo 3.2
 113
 114     @see XDocumentRepository
 115  */
 116 interface XDocumentMetadataAccess
 117 {
 118     interface XURI;
 119     interface XRepositorySupplier;
 120
 121     //-------------------------------------------------------------------------
 122     /** get the unique ODF element with the given metadata reference.
 123
 124         @param MetadataReference
 125             a metadata reference, comprising the stream name and the XML ID
 126             For example: Pair("content.xml", "foo-element-1")
 127
 128         @returns
 129             the ODF element with the given metadata references if it exists,
 130             else <NULL/>
 131      */
 132     XMetadatable getElementByMetadataReference(
 133         [in] com::sun::star::beans::StringPair MetadataReference);
 134
 135     //-------------------------------------------------------------------------
 136     /** get the ODF element that corresponds to an URI.
 137
 138         @param URI
 139             an URI that may identify an ODF element
 140
 141         @returns
 142             the ODF element that corresponds to the given URI, or <NULL/>
 143
 144         @throws com::sun::star::lang::IllegalArgumentException
 145             if the given URI is <NULL/>
 146      */
 147     XMetadatable getElementByURI([in] XURI URI)
 148         raises( com::sun::star::lang::IllegalArgumentException );
 149
 150     //-------------------------------------------------------------------------
 151     /** get the names of all metadata files with a given type.
 152
 153         @param Type
 154             the <code>rdf:type</code> property of the requested named graphs
 155
 156         @returns
 157             the names of all metadata graphs that have a <code>rdf:type</code>
 158             property with the given Type as object
 159
 160         @throws com::sun::star::lang::IllegalArgumentException
 161             if the given Type is <NULL/>
 162      */
 163     sequence<XURI> getMetadataGraphsWithType([in] XURI Type)
 164         raises( com::sun::star::lang::IllegalArgumentException );
 165
 166     //-------------------------------------------------------------------------
 167     /** add a metadata file to the manifest.
 168
 169         <p>
 170         This convenience method does the following:
 171         <ul>
 172         <li>create a new graph with the given name in the repository</li>
 173         <li>insert statements declaring the new graph to be a
 174             metadata file into the manifest graph</li>
 175         <li>insert statements declaring <code>rdf:type</code> properties
 176             for the new graph into the manifest graph</li>
 177         </ul>
 178         </p>
 179
 180         @param FileName
 181             the name of the stream in the ODF storage where the graph will
 182             be stored
 183
 184         @param Types
 185             a list of types that will be inserted as <code>rdf:type</code>
 186             properties for the graph
 187
 188         @returns
 189             the name of the new graph
 190
 191         @throws com::sun::star::lang::IllegalArgumentException
 192             if the FileName is invalid
 193
 194         @throws com::sun::star::container::ElementExistException
 195             if a stream with the given FileName already exists
 196      */
 197     XURI addMetadataFile([in] string FileName,
 198             [in] sequence<XURI> Types )
 199         raises( com::sun::star::lang::IllegalArgumentException,
 200                 com::sun::star::container::ElementExistException );
 201
 202     //-------------------------------------------------------------------------
 203     /** import a metadata file into the document repository, and add it to the
 204         manifest.
 205
 206         <p>
 207         This convenience method does the following:
 208         <li>import the given file into a graph with the given name
 209             in the repository</li>
 210         <li>insert statements declaring the new graph to be a
 211             metadata file into the manifest graph</li>
 212         <li>insert statements declaring <code>rdf:type</code> properties
 213             for the new graph into the manifest graph</li>
 214         </p>
 215
 216         @param FileName
 217             the name of the stream in the ODF storage where the graph will
 218             be stored
 219
 220         @param BaseURI
 221             a base URI to resolve relative URI references
 222
 223         @param Types
 224             a list of types that will be inserted as <code>rdf:type</code>
 225             properties for the graph
 226
 227         @returns
 228             the name of the new graph
 229
 230         @throws com::sun::star::lang::IllegalArgumentException
 231             if the given stream is <NULL/>,
 232             or BaseURI is <NULL/> and the format requires use of a base URI,
 233             or the FileName is invalid
 234
 235         @throws com::sun::star::datatransfer::UnsupportedFlavorException
 236             if the format requested is unknown or not supported
 237
 238         @throws com::sun::star::container::ElementExistException
 239             if a stream with the given FileName already exists
 240
 241         @throws ParseException
 242             if the input does not conform to the specified file format.
 243
 244         @throws com::sun::star::io::IOException
 245             if an I/O error occurs.
 246
 247         @see FileFormat
 248      */
 249     XURI importMetadataFile( [in] /*FileFormat*/ short Format,
 250             [in] com::sun::star::io::XInputStream InStream,
 251             [in] string FileName, [in] XURI BaseURI,
 252             [in] sequence<XURI> Types )
 253         raises( com::sun::star::lang::IllegalArgumentException,
 254                 com::sun::star::datatransfer::UnsupportedFlavorException,
 255                 com::sun::star::container::ElementExistException,
 256                 ParseException,
 257                 com::sun::star::io::IOException );
 258
 259     //-------------------------------------------------------------------------
 260     /** remove a metadata file from the manifest and the repository.
 261
 262         <p>
 263         This convenience method does the following:
 264         <li>delete the graph with the given GraphName in the repository</li>
 265         <li>remove the statements declaring the graph to be a
 266             metadata file from the manifest graph</li>
 267         </p>
 268
 269         @param GraphName
 270             the name of the graph that is to be removed
 271
 272         @throws com::sun::star::lang::IllegalArgumentException
 273             if the given GraphName is <NULL/>
 274
 275         @throws com::sun::star::container::NoSuchElementException
 276             if a graph with the given GraphName does not exist
 277      */
 278     void removeMetadataFile([in] XURI GraphName)
 279         raises( com::sun::star::lang::IllegalArgumentException,
 280                 com::sun::star::container::NoSuchElementException );
 281
 282     //-------------------------------------------------------------------------
 283     /** add a content or styles file to the manifest.
 284
 285         <p>
 286         This convenience method adds the required statements declaring a
 287         content or styles file to the manifest graph.
 288         <ul>
 289         <li>If the FileName ends in "content.xml",
 290             an <code>odf:ContentFile</code> is added.</li>
 291         <li>If the FileName ends in "styles.xml" ,
 292             an <code>odf:StylesFile</code>  is added.</li>
 293         <li>Other FileNames are invalid.</li>
 294         </ul>
 295         </p>
 296
 297         @param FileName
 298             the name of the stream in the ODF storage
 299
 300         @throws com::sun::star::lang::IllegalArgumentException
 301             if the FileName is invalid
 302
 303         @throws com::sun::star::container::ElementExistException
 304             if a stream with the given FileName already exists
 305      */
 306     void addContentOrStylesFile([in] string FileName)
 307         raises( com::sun::star::lang::IllegalArgumentException,
 308                 com::sun::star::container::ElementExistException );
 309
 310     //-------------------------------------------------------------------------
 311     /** remove a content or styles file from the manifest.
 312
 313         <p>
 314         This convenience method removes the statements declaring a
 315         content or styles file from the manifest graph.
 316         </p>
 317
 318         @param FileName
 319             the name of the stream in the ODF storage
 320
 321         @throws com::sun::star::lang::IllegalArgumentException
 322             if the FileName is invalid
 323
 324         @throws com::sun::star::container::NoSuchElementException
 325             if a graph with the given GraphName does not exist
 326      */
 327     void removeContentOrStylesFile([in] string FileName)
 328         raises( com::sun::star::lang::IllegalArgumentException,
 329                 com::sun::star::container::NoSuchElementException );
 330
 331     //-------------------------------------------------------------------------
 332     /** initialize document metadata from a storage.
 333
 334         <p>
 335         This method re-initializes the document metadata,
 336         loads the stream named "manifest.rdf" from the storage, and then
 337         loads all metadata streams mentioned in the manifest.
 338         </p>
 339
 340         <p>
 341         Note that it is not an error if the storage does not contain
 342         a manifest.
 343         In this case, the document metadata will be default initialized.
 344         </p>
 345
 346         <p>
 347         If an InteractionHandler argument is given, it will be used for
 348         error reporting. Otherwise, errors will be reported as exceptions.
 349         </p>
 350
 351         @param Storage
 352             a storage, representing e.g. an ODF package file, or sub-document
 353
 354         @param BaseURI
 355             a base URI to resolve relative URI references
 356             <p>N.B.: when loading from an ODF package, the base URI is not the
 357                URI of the package, but the URI of the directory in the package
 358                that contains the metadata.rdf</p>
 359
 360         @param InteractionHandler
 361             an InteractionHandler, used for error reporting
 362
 363         @throws com::sun::star::lang::IllegalArgumentException
 364             if any argument is <NULL/>
 365
 366         @throws com::sun::star::lang::WrappedTargetException
 367             if an error occurs while loading and no InteractionHandler given
 368      */
 369     void loadMetadataFromStorage(
 370             [in] com::sun::star::embed::XStorage Storage,
 371             [in] XURI BaseURI,
 372             [in] com::sun::star::task::XInteractionHandler InteractionHandler )
 373         raises( com::sun::star::lang::IllegalArgumentException,
 374                 com::sun::star::lang::WrappedTargetException );
 375
 376     //-------------------------------------------------------------------------
 377     /** store document metadata to a storage.
 378
 379         <p>
 380         This method stores all the graphs in the document metadata repository
 381         to the given storage.
 382         </p>
 383
 384         <p>
 385         Note that to be stored correctly, a named graph must have a complete
 386         entry in the manifest graph.
 387         </p>
 388
 389         @param Storage
 390             a storage, representing e.g. an ODF package file, or sub-document
 391
 392         @throws com::sun::star::lang::IllegalArgumentException
 393             if Storage argument is <NULL/>
 394
 395         @throws com::sun::star::lang::WrappedTargetException
 396             if an error occurs while loading
 397      */
 398     void storeMetadataToStorage(
 399             [in] com::sun::star::embed::XStorage Storage )
 400         raises( com::sun::star::lang::IllegalArgumentException,
 401                 com::sun::star::lang::WrappedTargetException );
 402
 403     //-------------------------------------------------------------------------
 404     /** loads document metadata from a medium.
 405
 406         <p>If the Medium contains an InteractionHandler, it will be used for
 407         error reporting.</p>
 408
 409         @param Medium
 410             the <type>com::sun::star::document::MediaDescriptor</type>
 411             representing the source
 412
 413         @throws com::sun::star::lang::IllegalArgumentException
 414             if the argument does not contain a URL or Stream property
 415
 416         @throws com::sun::star::lang::WrappedTargetException
 417             if an error occurs while loading
 418
 419         @see com::sun::star::document::MediaDescriptor
 420      */
 421     void loadMetadataFromMedium(
 422             [in] sequence < com::sun::star::beans::PropertyValue > Medium )
 423         raises( com::sun::star::lang::IllegalArgumentException,
 424                 com::sun::star::lang::WrappedTargetException );
 425
 426     //-------------------------------------------------------------------------
 427     /** stores document metadata to a medium.
 428
 429         @param Medium
 430             the <type>com::sun::star::document::MediaDescriptor</type>
 431             representing the target
 432
 433         @throws com::sun::star::lang::IllegalArgumentException
 434             if the argument does not contain a URL or Stream property
 435
 436         @throws com::sun::star::lang::WrappedTargetException
 437             if an error occurs while storing
 438
 439         @see com::sun::star::document::MediaDescriptor
 440      */
 441     void storeMetadataToMedium(
 442             [in] sequence < com::sun::star::beans::PropertyValue > Medium )
 443         raises( com::sun::star::lang::IllegalArgumentException,
 444                 com::sun::star::lang::WrappedTargetException );
 445
 446 };
 447
 448 //=============================================================================
 449
 450 }; }; }; };
 451
 452 #endif