xref: /trunk/main/offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl (revision 96af39f7)

/**************************************************************
 *
 * 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
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the 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_io_XInputStream_idl__
#include <com/sun/star/io/XInputStream.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_task_XInteractionHandler_idl__
#include <com/sun/star/task/XInteractionHandler.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.
    </p>

    <p>
    Note that this interface inherits from <type>XURI</type>: 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 OpenOffice 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 an URI.

        @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 );

    //-------------------------------------------------------------------------
    /** 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:
        <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>
        </p>

        @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:
        <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 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 <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 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 <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 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 );

};

//=============================================================================

}; }; }; };

#endif