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

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