offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28
  29 #ifndef __com_sun_star_rdf_XDocumentMetadataAccess_idl__
  30 #define __com_sun_star_rdf_XDocumentMetadataAccess_idl__
  31
  32 #include <com/sun/star/lang/IllegalArgumentException.idl>
  33 #include <com/sun/star/lang/WrappedTargetException.idl>
  34 #include <com/sun/star/beans/PropertyValue.idl>
  35 #include <com/sun/star/container/ElementExistException.idl>
  36 #include <com/sun/star/container/NoSuchElementException.idl>
  37 #include <com/sun/star/io/IOException.idl>
  38 #include <com/sun/star/io/XInputStream.idl>
  39 #include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
  40 #include <com/sun/star/embed/XStorage.idl>
  41 #include <com/sun/star/task/XInteractionHandler.idl>
  42 #include <com/sun/star/rdf/FileFormat.idl>
  43 #include <com/sun/star/rdf/ParseException.idl>
  44 #include <com/sun/star/rdf/XURI.idl>
  45 #include <com/sun/star/rdf/XMetadatable.idl>
  46 #include <com/sun/star/rdf/XRepositorySupplier.idl>
  47
  48
  49 //=============================================================================
  50
  51 module com {   module sun {   module star {   module rdf {
  52
  53 //=============================================================================
  54 /** document metadata functionality related to the "manifest.rdf".
  55
  56     <p>
  57     This interface contains some methods that create connections between
  58     the content and the RDF metadata of an ODF document.
  59     The main idea is to make querying and manipulating the
  60     data in the metadata manifest easier.
  61     </p>
  62
  63     <p>
  64     Note that this interface inherits from <type>XURI</type>: the
  65     base URI of the document is the string value of the RDF node.
  66     This is so that you can easily make RDF statements about the document.
  67     </p>
  68
  69     @since OOo 3.2
  70
  71     @see XDocumentRepository
  72  */
  73 interface XDocumentMetadataAccess
  74 {
  75     interface XURI;
  76     interface XRepositorySupplier;
  77
  78     //-------------------------------------------------------------------------
  79     /** get the unique ODF element with the given metadata reference.
  80
  81         @param MetadataReference
  82             a metadata reference, comprising the stream name and the XML ID
  83             For example: Pair("content.xml", "foo-element-1")
  84
  85         @returns
  86             the ODF element with the given metadata references if it exists,
  87             else <NULL/>
  88      */
  89     XMetadatable getElementByMetadataReference(
  90         [in] com::sun::star::beans::StringPair MetadataReference);
  91
  92     //-------------------------------------------------------------------------
  93     /** get the ODF element that corresponds to an URI.
  94
  95         @param URI
  96             an URI that may identify an ODF element
  97
  98         @returns
  99             the ODF element that corresponds to the given URI, or <NULL/>
 100
 101         @throws com::sun::star::lang::IllegalArgumentException
 102             if the given URI is <NULL/>
 103      */
 104     XMetadatable getElementByURI([in] XURI URI)
 105         raises( com::sun::star::lang::IllegalArgumentException );
 106
 107     //-------------------------------------------------------------------------
 108     /** get the names of all metadata files with a given type.
 109
 110         @param Type
 111             the <code>rdf:type</code> property of the requested named graphs
 112
 113         @returns
 114             the names of all metadata graphs that have a <code>rdf:type</code>
 115             property with the given Type as object
 116
 117         @throws com::sun::star::lang::IllegalArgumentException
 118             if the given Type is <NULL/>
 119      */
 120     sequence<XURI> getMetadataGraphsWithType([in] XURI Type)
 121         raises( com::sun::star::lang::IllegalArgumentException );
 122
 123     //-------------------------------------------------------------------------
 124     /** add a metadata file to the manifest.
 125
 126         <p>
 127         This convenience method does the following:
 128         <ul>
 129         <li>create a new graph with the given name in the repository</li>
 130         <li>insert statements declaring the new graph to be a
 131             metadata file into the manifest graph</li>
 132         <li>insert statements declaring <code>rdf:type</code> properties
 133             for the new graph into the manifest graph</li>
 134         </ul>
 135         </p>
 136
 137         @param FileName
 138             the name of the stream in the ODF storage where the graph will
 139             be stored
 140
 141         @param Types
 142             a list of types that will be inserted as <code>rdf:type</code>
 143             properties for the graph
 144
 145         @returns
 146             the name of the new graph
 147
 148         @throws com::sun::star::lang::IllegalArgumentException
 149             if the FileName is invalid
 150
 151         @throws com::sun::star::container::ElementExistException
 152             if a stream with the given FileName already exists
 153      */
 154     XURI addMetadataFile([in] string FileName,
 155             [in] sequence<XURI> Types )
 156         raises( com::sun::star::lang::IllegalArgumentException,
 157                 com::sun::star::container::ElementExistException );
 158
 159     //-------------------------------------------------------------------------
 160     /** import a metadata file into the document repository, and add it to the
 161         manifest.
 162
 163         <p>
 164         This convenience method does the following:
 165         <li>import the given file into a graph with the given name
 166             in the repository</li>
 167         <li>insert statements declaring the new graph to be a
 168             metadata file into the manifest graph</li>
 169         <li>insert statements declaring <code>rdf:type</code> properties
 170             for the new graph into the manifest graph</li>
 171         </p>
 172
 173         @param FileName
 174             the name of the stream in the ODF storage where the graph will
 175             be stored
 176
 177         @param BaseURI
 178             a base URI to resolve relative URI references
 179
 180         @param Types
 181             a list of types that will be inserted as <code>rdf:type</code>
 182             properties for the graph
 183
 184         @returns
 185             the name of the new graph
 186
 187         @throws com::sun::star::lang::IllegalArgumentException
 188             if the given stream is <NULL/>,
 189             or BaseURI is <NULL/> and the format requires use of a base URI,
 190             or the FileName is invalid
 191
 192         @throws com::sun::star::datatransfer::UnsupportedFlavorException
 193             if the format requested is unknown or not supported
 194
 195         @throws com::sun::star::container::ElementExistException
 196             if a stream with the given FileName already exists
 197
 198         @throws ParseException
 199             if the input does not conform to the specified file format.
 200
 201         @throws com::sun::star::io::IOException
 202             if an I/O error occurs.
 203
 204         @see FileFormat
 205      */
 206     XURI importMetadataFile( [in] /*FileFormat*/ short Format,
 207             [in] com::sun::star::io::XInputStream InStream,
 208             [in] string FileName, [in] XURI BaseURI,
 209             [in] sequence<XURI> Types )
 210         raises( com::sun::star::lang::IllegalArgumentException,
 211                 com::sun::star::datatransfer::UnsupportedFlavorException,
 212                 com::sun::star::container::ElementExistException,
 213                 ParseException,
 214                 com::sun::star::io::IOException );
 215
 216     //-------------------------------------------------------------------------
 217     /** remove a metadata file from the manifest and the repository.
 218
 219         <p>
 220         This convenience method does the following:
 221         <li>delete the graph with the given GraphName in the repository</li>
 222         <li>remove the statements declaring the graph to be a
 223             metadata file from the manifest graph</li>
 224         </p>
 225
 226         @param GraphName
 227             the name of the graph that is to be removed
 228
 229         @throws com::sun::star::lang::IllegalArgumentException
 230             if the given GraphName is <NULL/>
 231
 232         @throws com::sun::star::container::NoSuchElementException
 233             if a graph with the given GraphName does not exist
 234      */
 235     void removeMetadataFile([in] XURI GraphName)
 236         raises( com::sun::star::lang::IllegalArgumentException,
 237                 com::sun::star::container::NoSuchElementException );
 238
 239     //-------------------------------------------------------------------------
 240     /** add a content or styles file to the manifest.
 241
 242         <p>
 243         This convenience method adds the required statements declaring a
 244         content or styles file to the manifest graph.
 245         <ul>
 246         <li>If the FileName ends in "content.xml",
 247             an <code>odf:ContentFile</code> is added.</li>
 248         <li>If the FileName ends in "styles.xml" ,
 249             an <code>odf:StylesFile</code>  is added.</li>
 250         <li>Other FileNames are invalid.</li>
 251         </ul>
 252         </p>
 253
 254         @param FileName
 255             the name of the stream in the ODF storage
 256
 257         @throws com::sun::star::lang::IllegalArgumentException
 258             if the FileName is invalid
 259
 260         @throws com::sun::star::container::ElementExistException
 261             if a stream with the given FileName already exists
 262      */
 263     void addContentOrStylesFile([in] string FileName)
 264         raises( com::sun::star::lang::IllegalArgumentException,
 265                 com::sun::star::container::ElementExistException );
 266
 267     //-------------------------------------------------------------------------
 268     /** remove a content or styles file from the manifest.
 269
 270         <p>
 271         This convenience method removes the statements declaring a
 272         content or styles file from the manifest graph.
 273         </p>
 274
 275         @param FileName
 276             the name of the stream in the ODF storage
 277
 278         @throws com::sun::star::lang::IllegalArgumentException
 279             if the FileName is invalid
 280
 281         @throws com::sun::star::container::NoSuchElementException
 282             if a graph with the given GraphName does not exist
 283      */
 284     void removeContentOrStylesFile([in] string FileName)
 285         raises( com::sun::star::lang::IllegalArgumentException,
 286                 com::sun::star::container::NoSuchElementException );
 287
 288     //-------------------------------------------------------------------------
 289     /** initialize document metadata from a storage.
 290
 291         <p>
 292         This method re-initializes the document metadata,
 293         loads the stream named "manifest.rdf" from the storage, and then
 294         loads all metadata streams mentioned in the manifest.
 295         </p>
 296
 297         <p>
 298         Note that it is not an error if the storage does not contain
 299         a manifest.
 300         In this case, the document metadata will be default initialized.
 301         </p>
 302
 303         <p>
 304         If an InteractionHandler argument is given, it will be used for
 305         error reporting. Otherwise, errors will be reported as exceptions.
 306         </p>
 307
 308         @param Storage
 309             a storage, representing e.g. an ODF package file, or sub-document
 310
 311         @param BaseURI
 312             a base URI to resolve relative URI references
 313             <p>N.B.: when loading from an ODF package, the base URI is not the
 314                URI of the package, but the URI of the directory in the package
 315                that contains the metadata.rdf</p>
 316
 317         @param InteractionHandler
 318             an InteractionHandler, used for error reporting
 319
 320         @throws com::sun::star::lang::IllegalArgumentException
 321             if any argument is <NULL/>
 322
 323         @throws com::sun::star::lang::WrappedTargetException
 324             if an error occurs while loading and no InteractionHandler given
 325      */
 326     void loadMetadataFromStorage(
 327             [in] com::sun::star::embed::XStorage Storage,
 328             [in] XURI BaseURI,
 329             [in] com::sun::star::task::XInteractionHandler InteractionHandler )
 330         raises( com::sun::star::lang::IllegalArgumentException,
 331                 com::sun::star::lang::WrappedTargetException );
 332
 333     //-------------------------------------------------------------------------
 334     /** store document metadata to a storage.
 335
 336         <p>
 337         This method stores all the graphs in the document metadata repository
 338         to the given storage.
 339         </p>
 340
 341         <p>
 342         Note that to be stored correctly, a named graph must have a complete
 343         entry in the manifest graph.
 344         </p>
 345
 346         @param Storage
 347             a storage, representing e.g. an ODF package file, or sub-document
 348
 349         @throws com::sun::star::lang::IllegalArgumentException
 350             if Storage argument is <NULL/>
 351
 352         @throws com::sun::star::lang::WrappedTargetException
 353             if an error occurs while loading
 354      */
 355     void storeMetadataToStorage(
 356             [in] com::sun::star::embed::XStorage Storage )
 357         raises( com::sun::star::lang::IllegalArgumentException,
 358                 com::sun::star::lang::WrappedTargetException );
 359
 360     //-------------------------------------------------------------------------
 361     /** loads document metadata from a medium.
 362
 363         <p>If the Medium contains an InteractionHandler, it will be used for
 364         error reporting.</p>
 365
 366         @param Medium
 367             the <type>com::sun::star::document::MediaDescriptor</type>
 368             representing the source
 369
 370         @throws com::sun::star::lang::IllegalArgumentException
 371             if the argument does not contain a URL or Stream property
 372
 373         @throws com::sun::star::lang::WrappedTargetException
 374             if an error occurs while loading
 375
 376         @see com::sun::star::document::MediaDescriptor
 377      */
 378     void loadMetadataFromMedium(
 379             [in] sequence < com::sun::star::beans::PropertyValue > Medium )
 380         raises( com::sun::star::lang::IllegalArgumentException,
 381                 com::sun::star::lang::WrappedTargetException );
 382
 383     //-------------------------------------------------------------------------
 384     /** stores document metadata to a medium.
 385
 386         @param Medium
 387             the <type>com::sun::star::document::MediaDescriptor</type>
 388             representing the target
 389
 390         @throws com::sun::star::lang::IllegalArgumentException
 391             if the argument does not contain a URL or Stream property
 392
 393         @throws com::sun::star::lang::WrappedTargetException
 394             if an error occurs while storing
 395
 396         @see com::sun::star::document::MediaDescriptor
 397      */
 398     void storeMetadataToMedium(
 399             [in] sequence < com::sun::star::beans::PropertyValue > Medium )
 400         raises( com::sun::star::lang::IllegalArgumentException,
 401                 com::sun::star::lang::WrappedTargetException );
 402
 403 };
 404
 405 //=============================================================================
 406
 407 }; }; }; };
 408
 409 #endif
 410
 411 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */