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