Metadata API
From Apache OpenOffice Wiki
Description
This is a draft proposal for a RDF metadata API.
Resource Description Framework The ODF metadata specification
Comments
Leo Sauermann 31.3.2008 (I am a long-time RDF user and contributed to RDF2Go, Sesame, and used Jena for years, the java apis, also did other stuff with rdf in python and php)
- For the RDFFileFormat, use the mimetypes listed in RDF2go.
- You can make a method in Statement - getReifiedStatement - that returns a reified statement.
- Make XRDFReifiedStatement a subclass of XRDFResource - add getStatement there to return the statment it reifies (this is like in Jena ReifiedStatement/Java)
- destroyGraph sounds weird - deleteGraph?
- I would do an Interface for the querySelect results. (XRDFQueryResultTable). They can be serialized and deserialized, ...passing a nice object around is maybe better here
- You should add query methods to RDFRepository for finding statements find(s,p,o, [optional[context]]). These return QUADS - statements with a fourth column, the graph name
- add XRDFContextStatement with a XRDFREsource as context - then you can return these as results of find mehtods in RDFRepository
- add addStatement and RemoveStatement to RDFRepository, but passing in XRDFContextStatement
- RDFNamespaces: add RDFS, Dublin Core, FOAF.
- although its not conformant, making a constructor for blank nodes with a passeable string can be handy sometimes. Still, better don't do it...hm. not very helpful :-)
- On the long run, you may want to add transactions:
- XRDFRepositorySupplier is the main repository then.
- XRDFRepository is a transaction.
- XRDFRepository gets the methods: commit, rollback, isChanged(), setAutoCommit (true/false - setting to true commits after each command), getAutoCommit...
API Draft
/* API for RDF (Resource Description Framework) metadata & such. the main parts: the RDF model part: - XRDFRepository a set of named RDF graphs basically, this is where the metadata lives - XRDFNamedGraph a single named graph this likely would be implemented as just a shim with the graph name and pointer to the repository - XRDFNode, XRDFResource, XRDFBlankNode, XRDFURI, XRDFLiteral RDF node types these would ideally be value types, but we do need subtype polymorphism... - XRDFStatement RDF triple: subject, predicate, object the document integration part: - XRDFRepositorySupplier implemented at the document to supply the (per-document) XRDFRepository - XManifestAccess implemented at the document; contains integration between document content and meta-data - XMetadatable: this must be implemented by every ODF element in the various document types that may have xml:id attribute; basically, it makes the XML ID attribute available note that the two parts must communicate only via this API; no XUnoTunnel etc. allowed. */ module com { module sun { module star { module util /*FIXME: or lang or something*/ { //============================================================================= /** A tuple, or pair. <p> This structure allows for conveniently packing together two values of any type, and could be useful as the result type of methods. </p> @since OOo 3.0 */ struct Pair<T, U> { /// first object T First; /// second object U Second; }; //============================================================================= }; }; }; }; //FIXME: where to put this module? here? below css.document? below css.xml? module com { module sun { module star { module rdf { //============================================================================= /** represents a node that may occur in a RDF graph. //FIXME paint a picture XRDFNode | |---XRDFLiteral | XRDFResource | |---XRDFBlankNode | XRDFURI @since OOo 3.0 @see XRDFRepository */ interface XRDFNode { [readonly, attribute] string StringValue; }; //============================================================================= /** represents a resource node that may occur in a RDF graph. <p> Note that this interface exists only to separate resources from literals. </p> @since OOo 3.0 @see XRDFRepository */ interface XRDFResource : XRDFNode { }; //============================================================================= /** represents a blank node that may occur in a RDF graph. <p> Blank nodes are distinct, but have no URI; in other words, they are resources that are anonymous. </p> @since OOo 3.0 @see XRDFRepository */ interface XRDFBlankNode : XRDFResource { }; //============================================================================= /** represents an URI node that may occur in a RDF graph. //FIXME: URI or IRI or what? <p> Note that this is actually an IRI, but the RDF literature speaks of URIs only, so we chose to use established terminology. </p> @since OOo 3.0 @see XRDFRepository */ interface XRDFURI : XRDFResource { [readonly, attribute] string LocalName; [readonly, attribute] string Namespace; }; //============================================================================= /** represents a literal that may occur in a RDF graph. @since OOo 3.0 @see XRDFRepository */ interface XRDFLiteral : XRDFNode { [readonly, attribute] string Language; [readonly, attribute] string Datatype; //FIXME: TODO: have not looked at handling all kinds of types, maybe just have an any attr here... }; //FIXME: do we need a factory for Nodes? /* or instead, use new style services:*/ service RDFBlankNode : XRDFBlankNode { // FIXME: hmmm, does it make sense to allow creating arbitrary blank nodes? // maybe we should have no-param create() that guarantees uniqueness of the new node? create( [in] string NodeID ); /** create a new, unique blank node */ // FIXME hmm, unique as in distinct from all blank nodes in all repositories? argh... // create(); }; service RDFURI : XRDFURI { create( [in] string Value ) raises( com::sun::star::lang::IllegalArgumentException ); create2( [in] string Namespace, [in] string LocalName ) raises( com::sun::star::lang::IllegalArgumentException ); }; service RDFLiteral : XRDFLiteral { create( [in] string Value ); createWithType( [in] string Value, [in] string Type ); createWithLanguage( [in] string Value, [in] string Language ); // NOTE: there is no createWithTypeAndLanguage! }; //============================================================================= /** represents a RDF statement, or triple. @since OOo 3.0 @see XRDFRepository */ //FIXME hmm, if Stmt inherited from XRDFNode, we would get convenient reification... // for some value of convenient: actually this would require that we be able to deterministically compute a unique Resource // from only the contents of the triple, like e.g. a cryptographic hash (so we can use it as the subject of reification) interface XRDFStatement // : XRDFNode { [readonly, attribute] XRDFResource Subject; [readonly, attribute] XRDFResource Predicate; [readonly, attribute] XRDFNode Object; }; //FIXME: would a base RDFException make sense? //============================================================================= /** represents an error condition that is signalled on parsing an RDF file. @since OOo 3.0 @see XRDFRepository */ exception RDFParseException : com::sun::star::uno::Exception { }; //============================================================================= /** represents an error condition that is signalled on evaluating a query against an RDF Repository. @since OOo 3.0 @see XRDFRepository */ exception RDFQueryException : com::sun::star::uno::Exception { }; //============================================================================= /** represents an error condition that is signalled on accessing an RDF Repository. @since OOo 3.0 @see XRDFRepository */ exception RDFRepositoryException : com::sun::star::uno::Exception { }; //============================================================================= /** provides access to an RDF Repository. @since OOo 3.0 @see XRDFRepository */ interface XRDFRepositorySupplier { //------------------------------------------------------------------------- /** provides the RDF Repository associated with this object. @returns an object of type <type>XRDFRepository</type> */ XRDFRepostiory getRDFRepository(); }; //============================================================================= /** provides access to a set of named RDF graphs. <p> A repository for storing information according to the data model of the <a href="http://www.w3.org/RDF/">Resource Description Framework</a>. The RDF triples are stored as a set of named RDF graphs. Importing and exporting files in the <a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a> format is supported. Support for other file formats is optional. Support for querying the repository with the <a href="http://www.w3.org/TR/rdf-sparql-query/">SPARQL</a> query language is provided. </p> @since OOo 3.0 @see XRDFRepositorySupplier */ interface XRDFRepository { //------------------------------------------------------------------------- /** imports a named graph into the repository. <p> Implementations must support RDF/XML format. Support for other RDF formats is optional. If the format is not supported by the implementation, an <type>UnsupportedFlavorException</type> is raised. </p> @param Format the format of the input file @param InStream the input stream, containing an RDF file in the specified format @param GraphName the name of the graph that is imported @throws com::sun::star::lang::IllegalArgumentException if the given stream is <NULL/> @throws com::sun::star::datatransfer::UnsupportedFlavorException if the format requested is unknown or not supported //FIXME: what if GraphName is already in the repository? replace it, or throw? i think i prefer throwing... @throws com::sun::star::container::ElementExistException if a graph with the given GraphName already exists in the repository @throws RDFParseException if the input does not conform to the specified file format. @throws RDFRepositoryException if an error occurs when accessing the repository. @throws com::sun::star::io::IOException if an I/O error occurs. @see RDFFileFormat */ void importGraph([in] RDFFileFormat Format, [in] com::sun::star::io::XInputStream InStream, [in] string GraphName) raises( com::sun::star::lang::IllegalArgumentException, com::sun::star::datatransfer::UnsupportedFlavorException, com::sun::star::container::ElementExistException, RDFParseException, RDFRepositoryException, com::sun::star::io::IOException ); //------------------------------------------------------------------------- /** exports a named graph from the repository. <p> Implementations must support RDF/XML format. Support for other RDF formats is optional. If the format is not supported by the implementation, an <type>UnsupportedFlavorException</type> is raised. </p> @param Format the format of the output file @param OutStream the target output stream @param GraphName the name of the graph that is to be exported @throws com::sun::star::lang::IllegalArgumentException if the given stream is <NULL/> @throws com::sun::star::datatransfer::UnsupportedFlavorException if the format requested is unknown or not supported @throws com::sun::star::container::NoSuchElementException if a graph with the given GraphName does not exist @throws RDFRepositoryException if an error occurs when accessing the repository. @throws com::sun::star::io::IOException if an I/O error occurs. @see RDFFileFormat */ void exportGraph([in] RDFFileFormat Format, [in] com::sun::star::io::XOutputStream OutStream, [in] string GraphName) raises( com::sun::star::lang::IllegalArgumentException, com::sun::star::datatransfer::UnsupportedFlavorException, com::sun::star::container::NoSuchElementException, RDFRepositoryException, com::sun::star::io::IOException ); //------------------------------------------------------------------------- /** gets the names of all the graphs in the repository. //FIXME: except "unspecified" graphs for RDFa, i guess... @returns a list containing the names of the graphs in the repository @throws RDFRepositoryException if an error occurs when accessing the repository. */ sequence<string> getGraphNames() raises( RDFRepositoryException ); //------------------------------------------------------------------------- /** gets a graph by its name. @param GraphName the name of the graph that is to be returned @returns the graph with the given name if it exists, else <NULL/> @throws RDFRepositoryException if an error occurs when accessing the repository. */ XRDFNamedGraph getGraph([in] string GraphName) raises( RDFRepositoryException ); //------------------------------------------------------------------------- /** creates a graph with the given name. <p> The name must be unique within the repository. The name must be a valid file name in an ODF package. //FIXME: clarify a bit more? </p> @param GraphName the name of the graph that is to be created @returns the graph with the given name @throws com::sun::star::lang::IllegalArgumentException if the given GraphName is invalid @throws com::sun::star::container::ElementExistException if a graph with the given GraphName already exists @throws RDFRepositoryException if an error occurs when accessing the repository. */ XRDFNamedGraph createGraph([in] string GraphName) raises( com::sun::star::container::ElementExistException, com::sun::star::lang::IllegalArgumentException, RDFRepositoryException ); //------------------------------------------------------------------------- /** destroys the graph with the given name, and removes it from the repository. <p> This invalidates any instances of XRDFNamedGraph for the parameter. </p> @param GraphName the name of the graph that is to be destroyed @throws com::sun::star::container::NoSuchElementException if a graph with the given GraphName does not exist @throws RDFRepositoryException if an error occurs when accessing the repository. */ void destroyGraph([in] string GraphName) raises( com::sun::star::container::NoSuchElementException, RDFRepositoryException ); //------------------------------------------------------------------------- /** executes a SPARQL "SELECT" query. //FIXME: remove this? seems redundant? do we want to have _both_ iterator-returning and sequence-returning queries??? <p> This method runs a SPARQL query that returns a list of variable bindings, i.e., a query beginning with "SELECT". The result is basically a (rectangular) table with labeled columns, where individual cells may be <NULL/>. </p> @param Query the SPARQL query string @returns a pair, containing <li>a list of query variable names (column labels)</li> <li>a list of query results (rows), each being a list of bindings for the above variables</li> @throws RDFQueryException if the query string is malformed, or evaluation fails @throws RDFRepositoryException if an error occurs when accessing the repository. */ Pair<sequence<string>,sequence<sequence<XRDFNode> > > querySelect([in] string Query) raises( RDFQueryException, RDFRepositoryException ); //------------------------------------------------------------------------- /** executes a SPARQL "SELECT" query. <p> This method runs a SPARQL query that returns a list of variable bindings, i.e., a query beginning with "SELECT". The result is basically a (rectangular) table with labeled columns, where individual cells may be <NULL/>. </p> @param Query the SPARQL query string @returns a pair, containing <li>a list of query variable names (column labels)</li> <li>an iterator of query results (rows), each being a list of bindings for the above variables</li> //FIXME: do we need example result here, or is this clear enough? @throws RDFQueryException if the query string is malformed, or evaluation fails @throws RDFRepositoryException if an error occurs when accessing the repository. */ // Pair<sequence<string>,XRDFIterator<sequence<XRDFNode>>> querySelect([in] string Query) Pair<sequence<string>,com::sun::star::container::XEnumeration/*<sequence<XRDFNode>>*/> querySelect([in] string Query) raises( RDFQueryException, RDFRepositoryException ); //------------------------------------------------------------------------- /** executes a SPARQL "CONSTRUCT" query. <p> This method runs a SPARQL query that constructs a result graph, i.e., a query beginning with "CONSTRUCT". </p> @param Query the SPARQL query string @returns an iterator over the query result graph @throws RDFQueryException if the query string is malformed, or evaluation fails @throws RDFRepositoryException if an error occurs when accessing the repository. */ // XRDFIterator<XRDFStatement> queryConstruct([in] string Query) com::sun::star::container::XEnumeration/*<XRDFStatement>*/ queryConstruct([in] string Query) raises( RDFQueryException, RDFRepositoryException ); //------------------------------------------------------------------------- /** executes a SPARQL "ASK" query. <p> This method runs a SPARQL query that computes a boolean, i.e., a query beginning with "ASK". </p> @param Query the SPARQL query string @returns the boolean query result @throws RDFQueryException if the query string is malformed, or evaluation fails @throws RDFRepositoryException if an error occurs when accessing the repository. */ boolean queryAsk([in] string Query) raises( RDFQueryException, RDFRepositoryException ); //FIXME: how to handle inference? as a query parameter? in constructor? // have a supportsInference() here? inference is, at most, optional... //FIXME namespaces??? sesame has support for registering ns prefixes here. // this might be convenient. or it might be superfluous. //------------------------------------------------------------------------- /** update the RDFa statement(s) that correspond to an ODF element in the repository. <p> This method will do the following steps: <li>Remove all RDFa statements that involve the Object parameter from the repository</li> <li>If the RDFaContent parameter is the empty string, add the following RDF statement to an unspecified named graph: <li>Subject Predicate XRDFLiteral(Object->getText())</li> </li> <li>If the RDFaContent parameter is not the empty string, add the following RDFa statements to an unspecified named graph: <li>Subject Predicate XRDFLiteral(RDFaContent^^RDFaDatatype)</li> <li>Subject rdfs:label XRDFLiteral(Object->getText())</li> </li> </p> <p> RDFa statements are handled specially because they are not logically part of any graph. Also, they have rather unusual semantics. (Don't blame me, i didnt write that spec.) Also, just using addStatement for this would be ambiguous: if the object is a XMetadatable, do we insert the object itself (URI) or its literal content (RDFa)? </p> @param Subject the subject of the RDF triple. @param Predicate the predicate of the RDF triple. @param Object the object of the RDF triple is the text content of this parameter. @param RDFaContent the rdfa:content attribute (may be the empty string). @param RDFaContent the rdfa:datatype attribute (may be the empty string). @throws com::sun::star::lang::IllegalArgumentException if any parameter is <NULL/>, or Object is of a type that can not have RDFa meta data attached. @throws RDFRepositoryException if an error occurs when accessing the repository. */ // FIXME: if repo does not do transactions, this is maybe not atomic. error handling? // FIXME: how to call this ? setStatementFromContent? setStatementUsingContentLiteral? void setStatementRDFa([in] XRDFURI Subject, [in] XRDFURI Predicate, [in] com::sun::star::text::XTextRange Object, [in] string RDFaContent, [in] string RDFaDatatype) raises( com::sun::star::lang::IllegalArgumentException, RDFRepositoryException ); //------------------------------------------------------------------------- /** remove the RDFa statement(s) that correspond to an ODF element from the repository. <p> RDFa statements are handled specially because they are not logically part of any graph. (Don't blame me.) </p> @param Object the element whose RDFa statement(s) should be removed @throws com::sun::star::lang::IllegalArgumentException if the given Element is <NULL/>, or of a type that can not have RDFa meta data attached. @throws RDFRepositoryException if an error occurs when accessing the repository. */ void removeStatementRDFa([in] com::sun::star::text::XTextRange Object) raises( com::sun::star::lang::IllegalArgumentException, RDFRepositoryException ); //------------------------------------------------------------------------- /** find the RDFa statement(s) associated with an ODF element. @param Element the ODF element for which RDFa statements should be found @returns <li>if the element has no RDFa meta-data attributes: Pair(<NULL/>, <NULL/>)</li> <li>if the element has RDFa meta-data attributes, and no rdfa:content attached: Pair(RDFa-statement, <NULL/>)</li> <li>if the element has RDFa meta-data attributes, and also rdfa:content attached: Pair(RDFa-statement, RDFa-labels-statement)</li> @throws com::sun::star::lang::IllegalArgumentException if the given Element is <NULL/>, or of a type that can not have RDFa meta data attached. @throws RDFRepositoryException if an error occurs when accessing the repository. */ Pair<XRDFStatement,XRDFStatement> getStatementRDFa( [in] XMetadatable Element) raises( com::sun::star::lang::IllegalArgumentException, RDFRepositoryException ); }; //============================================================================= /** provides access to a set of named RDF graphs. @since OOo 3.0 @see XRDFRepository @see XRDFRepositorySupplier */ service RDFRepository : XRDFRepository { /** constructs repository with in-memory storage. */ create(); // FIXME: if we want to support HTTP/SQL-based storage, or inference, define more constructors here }; //============================================================================= /** represents an RDF named graph that is stored in an RDF Repository. // FIXME: do we need this at all??? // we could do all this at the XRDFRepository, w/ graph URI parameter // but i find it more convenient to have this extra type // also, it allows inheriting from XRDFNode, with useful semantics: <p> Note that this interface inherits from XRDFResource: the name of the graph is the string value of the RDF node. This is so that you can easily make RDF statements about named graphs. </p> <p> Note that instances may be destroyed via <method>XRDFRepository::destoryGraph()</method>. If a graph is destroyed, subsequent calls to <method>addStatement</method>, <method>removeStatement</method> will fail with an <type>NoSuchElementException</type>. </p> @since OOo 3.0 @see XRDFRepository */ interface XRDFNamedGraph : XRDFResource { //------------------------------------------------------------------------- /** returns the name of the graph. <p> The name is unique within the repository. </p> @returns the name of the graph */ string getName(); //------------------------------------------------------------------------- /** removes all statements from the graph. @throws RDFRepositoryException if an error occurs when accessing the repository. */ void clear() raises( RDFRepositoryException ); //------------------------------------------------------------------------- /** adds a RDF statement to the graph. <p> Note that the ODF elements that can have metadata attached all implement the interface XMetadatable, which inherits from XRDFResource, meaning that you can simply pass them in as parameters here, and it will magically work. </p> @param Subject the subject of the RDF triple. @param Predicate the predicate of the RDF triple. @param Object the object of the RDF triple. @throws com::sun::star::lang::IllegalArgumentException if any parameter is <NULL/> //FIXME: TODO: other cases? @throws com::sun::star::container::NoSuchElementException if this graph does not exist in the repository any more @throws RDFRepositoryException if an error occurs when accessing the repository. */ void addStatement([in] XRDFResource Subject, [in] XRDFResource Predicate, [in] XRDFNode Object) raises( com::sun::star::lang::IllegalArgumentException, com::sun::star::container::NoSuchElementException, RDFRepositoryException ); //------------------------------------------------------------------------- /** remove RDF statements from the graph. <p> Note that the ODF elements that can have metadata attached all implement the interface XMetadatable, which inherits from XRDFResource, meaning that you can simply pass them in as parameters here, and it will magically work. </p> <p> Any parameter may be <NULL/>, which acts as a wildcard. For example, to remove all statements about myURI: removeStatement(myURI, null, null) </p> @param Subject the subject of the RDF triple. @param Predicate the predicate of the RDF triple. @param Object the object of the RDF triple. @throws com::sun::star::lang::IllegalArgumentException if ... //FIXME: TODO: other cases? @throws com::sun::star::container::NoSuchElementException if this graph does not exist in the repository any more @throws RDFRepositoryException if an error occurs when accessing the repository. */ void removeStatements([in] XRDFResource Subject, [in] XRDFResource Predicate, [in] XRDFNode Object) raises( com::sun::star::lang::IllegalArgumentException, com::sun::star::container::NoSuchElementException, RDFRepositoryException ); //------------------------------------------------------------------------- /** gets RDF statements from a graph. <p> Note that the ODF elements that can have metadata attached all implement the interface XMetadatable, which inherits from XRDFResource, meaning that you can simply pass them in as parameters here, and it will magically work. </p> <p> Any parameter may be <NULL/>, which acts as a wildcard. For example, to get all statements about myURI: getStatements(myURI, null, null) </p> @param Subject the subject of the RDF triple. @param Predicate the predicate of the RDF triple. @param Object the object of the RDF triple. @returns an iterator over all RDF statements in the graph that match the parameters @throws com::sun::star::lang::IllegalArgumentException if ... //FIXME: TODO: other cases? @throws com::sun::star::container::NoSuchElementException if this graph does not exist in the repository any more @throws RDFRepositoryException if an error occurs when accessing the repository. */ XEnumeration/*<XRDFStatement>*/ getStatements([in] XRDFResource Subject, [in] XRDFResource Predicate, [in] XRDFNode Object) raises( com::sun::star::lang::IllegalArgumentException, com::sun::star::container::NoSuchElementException, RDFRepositoryException ); }; //============================================================================= /** Constants to specify the MIME types of RDF file formats. <p> These constants are mainly for use with <method>XRDFRepository::importGraph()</method> and <method>XRDFRepository::exportGraph()</method>. </p> @since OOo 3.0 @see XRDFRepository */ constants RDFFileFormat { /// <a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a> const string RDF_XML = "application/rdf+xml"; /// <a href="http://www.w3.org/DesignIssues/Notation3">N3 (Notation-3)</a> const string N3 = "text/rdf+n3"; /// <a href="http://www.w3.org/TR/rdf-testcases/#ntriples">N-Triples</a> const string NTRIPLES = "text/plain"; // argh!!! /// <a href="http://www.wiwiss.fu-berlin.de/suhl/bizer/TriG/Spec/">TriG</a> const string TRIG = "application/x-trig"; /// <a href="http://sw.nokia.com/trix/TriX.html">TriX</a> const string TRIX = "if only the damn server were up i'd know"; /// <a href="http://www.dajobe.org/2004/01/turtle/">Turtle</a> const string TURTLE = "application/turtle"; }; //============================================================================= /** Constants to specify some useful namespaces. @since OOo 3.0 @see XRDFRepository */ constants RDFNamespaces { //FIXME const structs are not legal IDL /// const StringPair RDF = "rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#"; const StringPair PKG = "pkg", "http://docs.oasis-open.org/opendocument/meta/package/common#"; const StringPair ODF = "odf", "http://docs.oasis-open.org/opendocument/meta/package/odf#"; }; //============================================================================= /** marks an object representing an ODF element that may have RDF meta data attached. <p> To make using ODF elements as part of RDF statements more convenient, this interface inherits from XRDFResource. </p> @since OOo 3.0 @see XRDFRepository */ //FIXME: inherit from XRDFResource ??? we can call createMapping, or just use the XmlId... interface XMetadatable : XRDFResource { //------------------------------------------------------------------------- /** an XML ID, comprising the stream name and the xml:id attribute. <p> Note that this ID must be unique for the ODF document. This implies that the xml:id part must be unique for every stream. The ID may be omitted, in which case the value is the empty string. For Example: "content.xml#foo-element-1" </p> */ [attribute] string XmlId { set raises ( com::sun::star::lang::IllegalArgumentException ); }; }; //============================================================================= /** misc stuff related to 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: URI pkg:idref XmlId. </p> <p> Note that this interface inherits from <type>XRDFResource</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 XRDFRepository */ // This is supposed to be implemented by the _document_, not the repository // FIXME: how to name this? // XDocumentMetadataAccess? // XDocumentRDF? // XDocumentRepositoryIntegration? // XDocumentManifest? // XPackageMetadata? // any other permutation? interface XManifestAccess : XRDFResource { //------------------------------------------------------------------------- /** 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/> */ XMetadatable getElementByURI([in] string URI); //------------------------------------------------------------------------- /** 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 */ // XRDFURI createMapping(XMetadatable Element); XRDFURI getOrCreateURIForElement([in] XMetadatable Element); //------------------------------------------------------------------------- /** 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, FIXME: throw or change mapping? </p> @param Element the ODF element for which an URI should be created */ // this one uses parameter uri // void createMapping([in] XMetadatable Element, [in] XRDFURI URI); void createMappingForElement([in] XMetadatable Element, [in] XRDFURI URI); //------------------------------------------------------------------------- /** 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/> */ XRDFURI getURIForElement([in] XMetadatable Element); }; //============================================================================= }; }; }; };
