INTEGRATION: CWS odfmetadata (1.1.2); FILE ADDED

2008/06/17 16:25:54 mst 1.1.2.2: - offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl:
+ storeMetadataToStorage: remove BaseURI parameter
+ importMetadataFile: add Types parameter
- offapi/com/sun/star/rdf/XURI.idl:
+ document URI splitting
2008/06/11 15:45:05 mst 1.1.2.1: #i90620#: add RDF API
- offapi/prj/{build.lst,d.lst}, offapi/util/makefile.mk:
+ add directory com/sun/star/rdf
- offapi/com/sun/star/modules.idl:
+ add module rdf
- offapi/com/sun/star/rdf:
+ add the RDF API idl files

1 files changed, 550 insertions, 0 deletions

diff --git a/offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl b/offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl
new file mode 100644
index 000000000000..6eda7bf0da0e
--- /dev/null
+++ b/offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl
@@ -0,0 +1,550 @@
+/*************************************************************************
+ *
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * Copyright 2008 by Sun Microsystems, Inc.
+ *
+ * OpenOffice.org - a multi-platform office productivity suite
+ *
+ * $RCSfile: XDocumentMetadataAccess.idl,v $
+ * $Revision: 1.2 $
+ *
+ * This file is part of OpenOffice.org.
+ *
+ * OpenOffice.org is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License version 3
+ * only, as published by the Free Software Foundation.
+ *
+ * OpenOffice.org is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License version 3 for more details
+ * (a copy is included in the LICENSE file that accompanied this code).
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with OpenOffice.org.  If not, see
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_rdf_XDocumentMetadataAccess_idl__
+#define __com_sun_star_rdf_XDocumentMetadataAccess_idl__
+
+#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
+#include <com/sun/star/lang/IllegalArgumentException.idl>
+#endif
+
+#ifndef __com_sun_star_lang_WrappedTargetException_idl__
+#include <com/sun/star/lang/WrappedTargetException.idl>
+#endif
+
+#ifndef __com_sun_star_beans_PropertyValue_idl__
+#include <com/sun/star/beans/PropertyValue.idl>
+#endif
+
+#ifndef __com_sun_star_container_ElementExistException_idl__
+#include <com/sun/star/container/ElementExistException.idl>
+#endif
+
+#ifndef __com_sun_star_container_NoSuchElementException_idl__
+#include <com/sun/star/container/NoSuchElementException.idl>
+#endif
+
+#ifndef __com_sun_star_io_IOException_idl__
+#include <com/sun/star/io/IOException.idl>
+#endif
+
+#ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__
+#include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
+#endif
+
+#ifndef __com_sun_star_embed_XStorage_idl__
+#include <com/sun/star/embed/XStorage.idl>
+#endif
+
+#ifndef __com_sun_star_io_XInputStream_idl__
+#include <com/sun/star/io/XInputStream.idl>
+#endif
+
+#ifndef __com_sun_star_rdf_FileFormat_idl__
+#include <com/sun/star/rdf/FileFormat.idl>
+#endif
+
+#ifndef __com_sun_star_rdf_ParseException_idl__
+#include <com/sun/star/rdf/ParseException.idl>
+#endif
+
+#ifndef __com_sun_star_rdf_XURI_idl__
+#include <com/sun/star/rdf/XURI.idl>
+#endif
+
+#ifndef __com_sun_star_rdf_XMetadatable_idl__
+#include <com/sun/star/rdf/XMetadatable.idl>
+#endif
+
+#ifndef __com_sun_star_rdf_XRepositorySupplier_idl__
+#include <com/sun/star/rdf/XRepositorySupplier.idl>
+#endif
+
+
+//=============================================================================
+
+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.
+    Among other things, the metadata manifest contains a mapping between ODF
+    elements (in the "content.xml" and "styles.xml" streams) and URIs.
+    Such a mapping works by associating the XML ID of the ODF element with
+    the URI by an RDF statement of the form:
+    <code>URI pkg:idref XmlId.</code>
+    </p>
+
+    <p>
+    Note that this interface inherits from <type>XResource</type>: the
+    UUID of the package is the string value of the RDF node.
+    This is so that you can easily make RDF statements about the package.
+    </p>
+
+    @since OOo 3.0
+
+    @see XDocumentRepository
+ */
+interface XDocumentMetadataAccess
+{
+    interface XURI;
+    interface XRepositorySupplier;
+
+    //-------------------------------------------------------------------------
+    /** get the UUID for the ODF package.
+
+        @returns
+            a universally unique ID that identifies this ODF package
+     */
+    string getPackageUUID();
+
+    //-------------------------------------------------------------------------
+    /** get the unique ODF element with the given XML ID.
+
+        @param XmlId
+            an XML ID, comprising the stream name and the "xml:id" attribute.
+            For example: "content.xml#foo-element-1"
+
+        @returns
+            the ODF element with the given XML ID if it exists, else <NULL/>
+     */
+    XMetadatable getElementByXmlId([in] string XmlId);
+
+    //-------------------------------------------------------------------------
+    /** get the ODF element that corresponds to an URI.
+
+        <p>
+        Convenience method that uses the mapping established in the
+        "manifest.rdf" to locate the ODF element corresponding to an URI.
+        </p>
+
+        @param URI
+            an 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 );
+
+    //-------------------------------------------------------------------------
+    /** find the URI that is associated with an ODF element in the manifest.
+
+        @param Element
+            the ODF element for which the URI should be returned
+
+        @returns
+            the URI associated with the element, or <NULL/>
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if the given Element is <NULL/>
+     */
+    XURI getURIForElement([in] XMetadatable Element)
+        raises( com::sun::star::lang::IllegalArgumentException );
+
+    //-------------------------------------------------------------------------
+    /** create an URI for an ODF element.
+
+        <p>
+        Convenience method that generates an URI for the given ODF element,
+        and inserts a mapping between the URI and the XML ID of the ODF element
+        into the manifest.
+        If the element does not have a XML ID yet, a new XML ID will be
+        generated.
+        If an URI for the element already exists, it will be returned.
+        </p>
+
+        @param Element
+            the ODF element for which an URI should be created.
+
+        @returns
+            the URI associated with the element
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if the given Element is <NULL/>
+     */
+    XURI getOrCreateURIForElement([in] XMetadatable Element)
+        raises( com::sun::star::lang::IllegalArgumentException );
+
+    //-------------------------------------------------------------------------
+    /** establish mapping between an ODF Element and an URI in the manifest.
+
+        <p>
+        This method Convenience method that generates an URI for the given
+        ODF element, and inserts a mapping between the URI and the XML ID
+        of the ODF element into the manifest.
+        If the element does not have a XML ID yet, a new XML ID will be
+        generated.
+        If there already exists an URI for the element, the mapping will not
+        be changed, and an
+        <type scope="com::sun::star::container">ElementExistException</type>
+        will be thrown.
+        </p>
+
+        <p>
+        Note that the mapping maintained by this method is a one-to-one
+        mapping, even though the specification technically permits
+        mapping an XML ID to multiple URIs.
+        </p>
+
+        @param Element
+            the ODF element with which an URI should be associated
+
+        @param URI
+            the URI which should be associated with the Element
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if any argument is <NULL/>
+
+        @throws com::sun::star::container::ElementExistException
+            if either the URI or the XML ID of the Element is already mapped
+     */
+    void createMappingForElement([in] XMetadatable Element, [in] XURI URI)
+        raises( com::sun::star::lang::IllegalArgumentException,
+                com::sun::star::container::ElementExistException );
+
+    //-------------------------------------------------------------------------
+    /** removes mapping for an ODF element from the manifest.
+
+        @param Element
+            the ODF element for which the mapping should be removed
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if the given Element is <NULL/>
+     */
+    void removeMappingForElement([in] XMetadatable Element)
+        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 GraphName in the repository</li>
+        <li>insert the required 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 package where the graph will
+            be stored
+
+        @param GraphName
+            the name of the graph that is to be created
+
+        @param Types
+            a list of types that will be inserted as <code>rdf:type</code>
+            properties for the graph
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if the given GraphName is <NULL/>, or the FileName is invalid
+
+        @throws com::sun::star::container::ElementExistException
+            if a graph with the given GraphName, or a stream with the given
+            FileName, already exists
+     */
+    void addMetadataFile([in] string FileName, [in] XURI GraphName,
+            [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:
+        <li>import the given file into a graph with the given GraphName
+            in the repository</li>
+        <li>insert the required statements declaring the new graph to be a
+            metadata file into the manifest graph</li>
+        </p>
+
+        @param FileName
+            the name of the stream in the ODF package where the graph will
+            be stored
+
+        @param GraphName
+            the name of the graph that is to be created
+
+        @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
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if the given stream or the GraphName 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 graph with the given GraphName, or 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
+     */
+    void importMetadataFile( [in] /*FileFormat*/ short Format,
+            [in] com::sun::star::io::XInputStream InStream,
+            [in] string FileName, [in] XURI GraphName, [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:
+        <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>
+        </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 package
+
+        @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, as well as
+        all mappings that refer to the file.
+        </p>
+
+        @param FileName
+            the name of the stream in the ODF package
+
+        @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>
+
+        @param Storage
+            a storage, representing e.g. an ODF package file
+
+        @param BaseURI
+            a base URI to resolve relative URI references
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if any argument is <NULL/>
+     */
+//FIXME: how to do error handling??? this thing must be able to report any number of errors in any number of streams... XInteractionHandler???
+    void loadMetadataFromStorage(
+            [in] com::sun::star::embed::XStorage Storage,
+            [in] XURI BaseURI)
+        raises( com::sun::star::lang::IllegalArgumentException );
+//                com::sun::star::io::IOException,
+//                com::sun::star::);
+
+    //-------------------------------------------------------------------------
+    /** 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, with a <code>pkg:path</code> property
+        that denotes a legal stream name.
+        </p>
+
+        @param Storage
+            a storage, representing e.g. an ODF package file
+
+        @throws com::sun::star::lang::IllegalArgumentException
+            if any argument is <NULL/>
+     */
+//FIXME error handling
+    void storeMetadataToStorage(
+            [in] com::sun::star::embed::XStorage Storage)
+        raises( com::sun::star::lang::IllegalArgumentException );
+//                com::sun::star::io::IOException,
+//                com::sun::star:: );
+
+//FIXME error handling for these?
+//Note: any errors when accessing individual streams in the medium (including the manifest) will not be reported to the caller unless an XInteractionHandler is supplied.
+    //-------------------------------------------------------------------------
+    /** loads document metadata from a medium.
+
+        @param Medium
+            the <type>com::sun::star::document::MediaDescriptor</type>
+            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 thrown when trying to access the medium
+
+        @throws com::sun::star::io::IOException
+            if thrown when trying to access the medium
+
+        @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,
+                com::sun::star::io::IOException );
+
+    //-------------------------------------------------------------------------
+    /** stores document metadata to a medium.
+
+        @param Medium
+            the <type>com::sun::star::document::MediaDescriptor</type>
+            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 thrown when trying to access the medium
+
+        @throws com::sun::star::io::IOException
+            if thrown when trying to access the medium
+
+        @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,
+                com::sun::star::io::IOException );
+
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif