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