/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at
http://mozilla.org/MPL/2.0/.
*
* This file incorporates work covered by the following license notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed
* with this work for additional information regarding copyright
* ownership. The ASF licenses this file to you under the Apache
* License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at
http://www.apache.org/licenses/LICENSE-2.0 .
*/
module com { module sun { module star { module rdf {
/** document metadata functionality related to the "manifest.rdf".
<p>
This interface contains some methods that create connections between
the content and the RDF metadata of an ODF document.
The main idea is to make querying and manipulating the
data in the metadata manifest easier.
</p>
<p>
Note that this interface inherits from XURI: the
base URI of the document is the string value of the RDF node.
This is so that you can easily make RDF statements about the document.
</p>
@since OOo 3.2
@see XDocumentRepository
*/
interface XDocumentMetadataAccess
{
interface XURI;
interface XRepositorySupplier;
/** get the unique ODF element with the given metadata reference.
@param MetadataReference
a metadata reference, comprising the stream name and the XML ID
For example: Pair("content.xml", "foo-element-1")
@returns
the ODF element with the given metadata references if it exists,
else `NULL`
*/
XMetadatable getElementByMetadataReference(
[in] com::sun::star::beans::StringPair MetadataReference);
/** get the ODF element that corresponds to a URI.
@param URI
a URI that may identify an ODF element
@returns
the ODF element that corresponds to the given URI, or `NULL`
@throws com::sun::star::lang::IllegalArgumentException
if the given URI is `NULL`
*/
XMetadatable getElementByURI([in] XURI URI)
raises( com::sun::star::lang::IllegalArgumentException );
/** get the names of all metadata files with a given type.
@param Type
the <code>rdf:type</code> property of the requested named graphs
@returns
the names of all metadata graphs that have a <code>rdf:type</code>
property with the given Type as object
@throws com::sun::star::lang::IllegalArgumentException
if the given Type is `NULL`
*/
sequence<XURI> getMetadataGraphsWithType([in] XURI Type)
raises( com::sun::star::lang::IllegalArgumentException );
/** add a metadata file to the manifest.
<p>
This convenience method does the following:
<ul>
<li>create a new graph with the given name in the repository</li>
<li>insert statements declaring the new graph to be a
metadata file into the manifest graph</li>
<li>insert statements declaring <code>rdf:type</code> properties
for the new graph into the manifest graph</li>
</ul>
</p>
@param FileName
the name of the stream in the ODF storage where the graph will
be stored
@param Types
a list of types that will be inserted as <code>rdf:type</code>
properties for the graph
@returns
the name of the new graph
@throws com::sun::star::lang::IllegalArgumentException
if the FileName is invalid
@throws com::sun::star::container::ElementExistException
if a stream with the given FileName already exists
*/
XURI addMetadataFile([in] string FileName,
[in] sequence<XURI> Types )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::ElementExistException );
/** import a metadata file into the document repository, and add it to the
manifest.
<p>
This convenience method does the following:
<ol>
<li>import the given file into a graph with the given name
in the repository</li>
<li>insert statements declaring the new graph to be a
metadata file into the manifest graph</li>
<li>insert statements declaring <code>rdf:type</code> properties
for the new graph into the manifest graph</li>
</ol>
</p>
@param Format
the file format, see FileFormat
@param InStream
the input stream
@param FileName
the name of the stream in the ODF storage where the graph will
be stored
@param BaseURI
a base URI to resolve relative URI references
@param Types
a list of types that will be inserted as <code>rdf:type</code>
properties for the graph
@returns
the name of the new graph
@throws com::sun::star::lang::IllegalArgumentException
if the given stream is `NULL`,
or BaseURI is `NULL` and the format requires use of a base URI,
or the FileName is invalid
@throws com::sun::star::datatransfer::UnsupportedFlavorException
if the format requested is unknown or not supported
@throws com::sun::star::container::ElementExistException
if a stream with the given FileName already exists
@throws ParseException
if the input does not conform to the specified file format.
@throws com::sun::star::io::IOException
if an I/O error occurs.
@see FileFormat
*/
XURI importMetadataFile( [in] /*FileFormat*/ short Format,
[in] com::sun::star::io::XInputStream InStream,
[in] string FileName, [in] XURI BaseURI,
[in] sequence<XURI> Types )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::datatransfer::UnsupportedFlavorException,
com::sun::star::container::ElementExistException,
ParseException,
com::sun::star::io::IOException );
/** remove a metadata file from the manifest and the repository.
<p>
This convenience method does the following:
<ol>
<li>delete the graph with the given GraphName in the repository</li>
<li>remove the statements declaring the graph to be a
metadata file from the manifest graph</li>
</ol>
</p>
@param GraphName
the name of the graph that is to be removed
@throws com::sun::star::lang::IllegalArgumentException
if the given GraphName is `NULL`
@throws com::sun::star::container::NoSuchElementException
if a graph with the given GraphName does not exist
*/
void removeMetadataFile([in] XURI GraphName)
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::NoSuchElementException );
/** add a content or styles file to the manifest.
<p>
This convenience method adds the required statements declaring a
content or styles file to the manifest graph.
<ul>
<li>If the FileName ends in "content.xml",
an <code>odf:ContentFile</code> is added.</li>
<li>If the FileName ends in "styles.xml" ,
an <code>odf:StylesFile</code> is added.</li>
<li>Other FileNames are invalid.</li>
</ul>
</p>
@param FileName
the name of the stream in the ODF storage
@throws com::sun::star::lang::IllegalArgumentException
if the FileName is invalid
@throws com::sun::star::container::ElementExistException
if a stream with the given FileName already exists
*/
void addContentOrStylesFile([in] string FileName)
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::ElementExistException );
/** remove a content or styles file from the manifest.
<p>
This convenience method removes the statements declaring a
content or styles file from the manifest graph.
</p>
@param FileName
the name of the stream in the ODF storage
@throws com::sun::star::lang::IllegalArgumentException
if the FileName is invalid
@throws com::sun::star::container::NoSuchElementException
if a graph with the given GraphName does not exist
*/
void removeContentOrStylesFile([in] string FileName)
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::NoSuchElementException );
/** initialize document metadata from a storage.
<p>
This method re-initializes the document metadata,
loads the stream named "manifest.rdf" from the storage, and then
loads all metadata streams mentioned in the manifest.
</p>
<p>
Note that it is not an error if the storage does not contain
a manifest.
In this case, the document metadata will be default initialized.
</p>
<p>
If an InteractionHandler argument is given, it will be used for
error reporting. Otherwise, errors will be reported as exceptions.
</p>
@param Storage
a storage, representing e.g. an ODF package file, or sub-document
@param BaseURI
a base URI to resolve relative URI references
<p>N.B.: when loading from an ODF package, the base URI is not the
URI of the package, but the URI of the directory in the package
that contains the metadata.rdf</p>
@param InteractionHandler
an InteractionHandler, used for error reporting
@throws com::sun::star::lang::IllegalArgumentException
if any argument is `NULL`
@throws com::sun::star::lang::WrappedTargetException
if an error occurs while loading and no InteractionHandler given
*/
void loadMetadataFromStorage(
[in] com::sun::star::embed::XStorage Storage,
[in] XURI BaseURI,
[in] com::sun::star::task::XInteractionHandler InteractionHandler )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::lang::WrappedTargetException );
/** store document metadata to a storage.
<p>
This method stores all the graphs in the document metadata repository
to the given storage.
</p>
<p>
Note that to be stored correctly, a named graph must have a complete
entry in the manifest graph.
</p>
@param Storage
a storage, representing e.g. an ODF package file, or sub-document
@throws com::sun::star::lang::IllegalArgumentException
if Storage argument is `NULL`
@throws com::sun::star::lang::WrappedTargetException
if an error occurs while loading
*/
void storeMetadataToStorage(
[in] com::sun::star::embed::XStorage Storage )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::lang::WrappedTargetException );
/** loads document metadata from a medium.
<p>If the Medium contains an InteractionHandler, it will be used for
error reporting.</p>
@param Medium
the com::sun::star::document::MediaDescriptor
representing the source
@throws com::sun::star::lang::IllegalArgumentException
if the argument does not contain a URL or Stream property
@throws com::sun::star::lang::WrappedTargetException
if an error occurs while loading
@see com::sun::star::document::MediaDescriptor
*/
void loadMetadataFromMedium(
[in] sequence < com::sun::star::beans::PropertyValue > Medium )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::lang::WrappedTargetException );
/** stores document metadata to a medium.
@param Medium
the com::sun::star::document::MediaDescriptor
representing the target
@throws com::sun::star::lang::IllegalArgumentException
if the argument does not contain a URL or Stream property
@throws com::sun::star::lang::WrappedTargetException
if an error occurs while storing
@see com::sun::star::document::MediaDescriptor
*/
void storeMetadataToMedium(
[in] sequence < com::sun::star::beans::PropertyValue > Medium )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::lang::WrappedTargetException );
};
}; }; }; };
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
