From a21809727e549a4cd7614ba2f0b02c8512753074 Mon Sep 17 00:00:00 2001 From: Vladimir Glazounov Date: Tue, 1 Jul 2008 15:23:12 +0000 Subject: 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 --- .../com/sun/star/rdf/XDocumentMetadataAccess.idl | 550 +++++++++++++++++++++ 1 file changed, 550 insertions(+) create mode 100644 offapi/com/sun/star/rdf/XDocumentMetadataAccess.idl (limited to 'offapi/com/sun/star/rdf') 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 + * + * 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 +#endif + +#ifndef __com_sun_star_lang_WrappedTargetException_idl__ +#include +#endif + +#ifndef __com_sun_star_beans_PropertyValue_idl__ +#include +#endif + +#ifndef __com_sun_star_container_ElementExistException_idl__ +#include +#endif + +#ifndef __com_sun_star_container_NoSuchElementException_idl__ +#include +#endif + +#ifndef __com_sun_star_io_IOException_idl__ +#include +#endif + +#ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__ +#include +#endif + +#ifndef __com_sun_star_embed_XStorage_idl__ +#include +#endif + +#ifndef __com_sun_star_io_XInputStream_idl__ +#include +#endif + +#ifndef __com_sun_star_rdf_FileFormat_idl__ +#include +#endif + +#ifndef __com_sun_star_rdf_ParseException_idl__ +#include +#endif + +#ifndef __com_sun_star_rdf_XURI_idl__ +#include +#endif + +#ifndef __com_sun_star_rdf_XMetadatable_idl__ +#include +#endif + +#ifndef __com_sun_star_rdf_XRepositorySupplier_idl__ +#include +#endif + + +//============================================================================= + +module com { module sun { module star { module rdf { + +//============================================================================= +/** document metadata functionality related to the "manifest.rdf". + +

+ 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: + URI pkg:idref XmlId. +

+ +

+ Note that this interface inherits from XResource: 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. +

+ + @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 + */ + XMetadatable getElementByXmlId([in] string XmlId); + + //------------------------------------------------------------------------- + /** get the ODF element that corresponds to an URI. + +

+ Convenience method that uses the mapping established in the + "manifest.rdf" to locate the ODF element corresponding to an URI. +

+ + @param URI + an URI that may identify an ODF element + + @returns + the ODF element that corresponds to the given URI, or + + @throws com::sun::star::lang::IllegalArgumentException + if the given URI is + */ + 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 + + @throws com::sun::star::lang::IllegalArgumentException + if the given Element is + */ + XURI getURIForElement([in] XMetadatable Element) + raises( com::sun::star::lang::IllegalArgumentException ); + + //------------------------------------------------------------------------- + /** create an URI for an ODF element. + +

+ 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. +

+ + @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 + */ + XURI getOrCreateURIForElement([in] XMetadatable Element) + raises( com::sun::star::lang::IllegalArgumentException ); + + //------------------------------------------------------------------------- + /** establish mapping between an ODF Element and an URI in the manifest. + +

+ 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 + ElementExistException + will be thrown. +

+ +

+ 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. +

+ + @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 + + @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 + */ + 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 rdf:type property of the requested named graphs + + @returns + the names of all metadata graphs that have a rdf:type + property with the given Type as object + + @throws com::sun::star::lang::IllegalArgumentException + if the given Type is + */ + sequence getMetadataGraphsWithType([in] XURI Type) + raises( com::sun::star::lang::IllegalArgumentException ); + + //------------------------------------------------------------------------- + /** add a metadata file to the manifest. + +

+ This convenience method does the following: +

    +
  • create a new graph with the given GraphName in the repository
    • +
  • insert the required statements declaring the new graph to be a + metadata file into the manifest graph
    • +
  • insert statements declaring rdf:type properties + for the new graph into the manifest graph
    • +
+

+ + @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 rdf:type + properties for the graph + + @throws com::sun::star::lang::IllegalArgumentException + if the given GraphName is , 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 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. + +

+ This convenience method does the following: +

  • import the given file into a graph with the given GraphName + in the repository
    • +
  • insert the required statements declaring the new graph to be a + metadata file into the manifest graph
    • +

    + + @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 rdf:type + properties for the graph + + @throws com::sun::star::lang::IllegalArgumentException + if the given stream or the GraphName is , + or BaseURI is 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 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. + +

    + This convenience method does the following: +

  • delete the graph with the given GraphName in the repository
    • +
  • remove the statements declaring the graph to be a + metadata file from the manifest graph
    • +

    + + @param GraphName + the name of the graph that is to be removed + + @throws com::sun::star::lang::IllegalArgumentException + if the given GraphName is + + @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. + +

    + This convenience method adds the required statements declaring a + content or styles file to the manifest graph. +

      +
    • If the FileName ends in "content.xml", + an odf:ContentFile is added.
      • +
    • If the FileName ends in "styles.xml" , + an odf:StylesFile is added.
      • +
    • Other FileNames are invalid.
      • +
    +

    + + @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. + +

    + 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. +

    + + @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. + +

    + 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. +

    + +

    + 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. +

    + + @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 + */ +//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. + +

    + This method stores all the graphs in the document metadata repository + to the given storage. +

    + +

    + Note that to be stored correctly, a named graph must have a complete + entry in the manifest graph, with a pkg:path property + that denotes a legal stream name. +

    + + @param Storage + a storage, representing e.g. an ODF package file + + @throws com::sun::star::lang::IllegalArgumentException + if any argument is + */ +//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 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 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 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 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 -- cgit