Difference between revisions of "Metadata API"

Latest revision as of 12:45, 26 June 2008

Description

This is a draft proposal for a RDF metadata API.
Resource Description Framework The ODF metadata specification
API Draft

/*
 
API for RDF (Resource Description Framework) metadata & such.
 
the main parts:
 
 
the RDF model part:
- XRepository
  a set of named RDF graphs
  basically, this is where the metadata lives
 
- XNamedGraph
  a single named graph
  this likely would be implemented as just a shim with the graph name and
  pointer to the repository
 
- XNode, XResource, XBlankNode, XURI, XLiteral
  RDF node types
  these would ideally be value types, but we do need subtype polymorphism...
 
- XStatement
  RDF triple: subject, predicate, object
 
 
the document integration part:
- XRepositorySupplier
  implemented at the document to supply the (per-document) XRepository
 
- 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 beans {
 
//=============================================================================
/** 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;
};
 
//=============================================================================
 
}; }; }; };
 
module com {   module sun {   module star {   module rdf {
 
//=============================================================================
/** represents a node that may occur in a RDF graph.
 
//FIXME paint a picture
    XNode
    |
    |---XLiteral
    |
    XResource
    |
    |---XBlankNode
    |
    XURI
 
    @since OOo 3.0
 
    @see XRepository
 */
interface XNode
{
    [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 XRepository
 */
interface XResource : XNode
{
};
 
//=============================================================================
/** 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 XRepository
 */
interface XBlankNode : XResource
{
};
 
//=============================================================================
/** 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 XRepository
 */
interface XURI : XResource
{
    [readonly, attribute] string LocalName;
    [readonly, attribute] string Namespace;
};
 
//=============================================================================
/** represents a literal that may occur in a RDF graph.
 
    @since OOo 3.0
 
    @see XRepository
 */
interface XLiteral : XNode
{
    [readonly, attribute] string Value;
    [readonly, attribute] string Language;
    [readonly, attribute] XURI   Datatype;
    //FIXME: TODO: have not looked at handling all kinds of types, maybe just have an any attr here...
};
 
//=============================================================================
/** represents a blank node that may occur in a RDF graph.
 
    @since OOo 3.0
 
    @see XRepository
 */
service BlankNode : XBlankNode
{
    //-------------------------------------------------------------------------
    /** create a blank RDF node.
 
        <p>
        Be careful! With this constructor you can create a node that aliases
        another node that already exists in some repository.
        That may or may not be what you want.
        If you want to create a new blank node that is guaranteed to be unique,
        use <method>XRepository::createBlankNode</method>
        <p>
 
        @param NodeID
            the ID for the blank node.
 
        @see <method>XRepository::createBlankNode</method>
     */
    create( [in] string NodeID );
};
 
//=============================================================================
/** represents an URI node that may occur in a RDF graph.
 
    @since OOo 3.0
 
    @see XRepository
 */
service URI : XURI
{
 
    //-------------------------------------------------------------------------
    /** creates an URI RDF node.
 
        @param Value
            the URI, represented as string.
 
        @throws com::sun::star::lang::IllegalArgumentException
            if the argument does not represent a valid URI
     */
    create( [in] string Value )
        raises( com::sun::star::lang::IllegalArgumentException );
 
    //-------------------------------------------------------------------------
    /** creates an URI RDF node from namespace prefix and local name.
 
        @param Namespace 
            the namespace prefix of the URI, represented as string.
 
        @param Namespace 
            the local name of the URI, represented as string.
 
        @throws com::sun::star::lang::IllegalArgumentException
            if the arguments do not represent a valid URI
     */
    createNS( [in] string Namespace, [in] string LocalName )
        raises( com::sun::star::lang::IllegalArgumentException );
 
    //-------------------------------------------------------------------------
    /** creates an URI RDF node for a well-known URI.
 
        @param Id
            the URI, represented as a constant from <type>URIs</type>.
 
        @throws com::sun::star::lang::IllegalArgumentException
            if the argument is not a valid constant from <type>URIs</type>
 
        @see URIs
     */
    createKnown( [in] short Id )
        raises( com::sun::star::lang::IllegalArgumentException );
 
};
 
//=============================================================================
/** represents a literal that may occur in a RDF graph.
 
    @since OOo 3.0
 
    @see XRepository
 */
service Literal : XLiteral
{
    //-------------------------------------------------------------------------
    /** creates a plain literal RDF node.
 
        @param Value
            the string value of the literal
     */
    create( [in] string Value );
 
    //-------------------------------------------------------------------------
    /** creates a typed literal RDF node.
 
        @param Value
            the string value of the literal
 
        @param Type
            the data type of the literal
     */
    createWithType( [in] string Value, [in] XURI Type );
 
    //-------------------------------------------------------------------------
    /** creates a literal RDF node with a language.
 
        @param Value
            the string value of the literal
 
        @param Language
            the language of the literal
     */
    createWithLanguage( [in] string Value, [in] string Language );
 
    // NOTE: there is no createWithTypeAndLanguage!
};
 
 
//=============================================================================
/** represents a RDF statement, or triple.
 
    @since OOo 3.0
 
    @see XRepository
 */
//FIXME hmm, if Stmt inherited from XNode, 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)
// furthermore, is there a *standard way* to do it? if not, would not be interoperable?
// another idea: if we dont inherit XNode, why not make this a struct?
// better yet, why not have a Triple<XResource,XResource,XNode>?
/* REPLACED BY STRUCT STATEMENT!
interface XStatement // : XNode
{
    [readonly, attribute] XResource Subject;
    [readonly, attribute] XResource Predicate;
    [readonly, attribute] XNode     Object;
    [readonly, attribute] XURI      Graph;
};
*/
 
//=============================================================================
/** represents a RDF statement, or triple.
 
    @since OOo 3.0
 
    @see XRepository
 */
struct Statement
{
    XResource Subject;
    XResource Predicate;
    XNode     Object;
    /// the named graph that contains this statement, or <NULL/>.
    XURI      Graph;
};
 
//=============================================================================
/** represents a reified RDF statement.
 
    @since OOo 3.0
 
    @see XRepository
 */
interface XReifiedStatement : XResource
{
    [readonly, attribute] Statement Statement;
};
 
 
//=============================================================================
/** represents an error condition that is signalled on parsing an RDF file.
 
    @since OOo 3.0
 
    @see XRepository
 */
exception ParseException : 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 XRepository
 */
exception QueryException : com::sun::star::uno::Exception
{
};
 
//=============================================================================
/** represents an error condition that is signalled on accessing an RDF
    Repository.
 
    @since OOo 3.0
 
    @see XRepository
 */
exception RepositoryException : com::sun::star::uno::Exception
{
};
 
 
//=============================================================================
/** provides access to an RDF Repository.
 
    @since OOo 3.0
 
    @see XRepository
 */
interface XRepositorySupplier
{
    //-------------------------------------------------------------------------
    /** provides the RDF Repository associated with this object.
 
        @returns
            an object of type <type>XRepository</type>
     */
    XRepository 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 XRepositorySupplier
 */
interface XRepository
{
    //-------------------------------------------------------------------------
    /** creates a fresh unique blank node.
 
        @returns
            a newly generated blank node which is unique in this repository
     */
    XBlankNode createBlankNode();
 
 
    //-------------------------------------------------------------------------
    /** 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
 
        @throws com::sun::star::container::ElementExistException
            if a graph with the given GraphName already exists in the
            repository
 
        @throws ParseException
            if the input does not conform to the specified file format.
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
 
        @throws com::sun::star::io::IOException
            if an I/O error occurs.
 
        @see FileFormat
     */
    XNamedGraph importGraph([in] FileFormat Format,
                [in] com::sun::star::io::XInputStream InStream,
                [in] XURI GraphName)
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::datatransfer::UnsupportedFlavorException,
                com::sun::star::container::ElementExistException,
                ParseException,
                RepositoryException,
                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 RepositoryException
            if an error occurs when accessing the repository.
 
        @throws com::sun::star::io::IOException
            if an I/O error occurs.
 
        @see FileFormat
     */
    void exportGraph([in] FileFormat Format,
                [in] com::sun::star::io::XOutputStream OutStream,
                [in] XURI GraphName)
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::datatransfer::UnsupportedFlavorException,
                com::sun::star::container::NoSuchElementException,
                RepositoryException,
                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 RepositoryException
            if an error occurs when accessing the repository.
     */
    sequence<XURI> getGraphNames()
        raises( RepositoryException );
 
    //-------------------------------------------------------------------------
    /** 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 RepositoryException
            if an error occurs when accessing the repository.
     */
    XNamedGraph getGraph([in] XURI GraphName)
        raises( RepositoryException );
 
    //-------------------------------------------------------------------------
    /** creates a graph with the given name.
 
        <p>
        The name must be unique within the repository.
        </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 RepositoryException
            if an error occurs when accessing the repository.
     */
    XNamedGraph createGraph([in] XURI GraphName)
        raises( com::sun::star::container::ElementExistException,
                com::sun::star::lang::IllegalArgumentException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** destroys the graph with the given name, and removes it from the
        repository.
 
        <p>
        This invalidates any instances of XNamedGraph 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 RepositoryException
            if an error occurs when accessing the repository.
     */
    void destroyGraph([in] XURI GraphName)
        raises( com::sun::star::container::NoSuchElementException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** gets matching RDF statements from the repository.
 
        <p>
        Any parameter may be <NULL/>, which acts as a wildcard.
        For example, to get all statements about myURI:
        <code>getStatements(myURI, null, null)</code>
        </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 repository that match
            the parameters, represented as an
            enumeration of <type>XStatement</type>
 
        @throws com::sun::star::lang::IllegalArgumentException
            if ... //FIXME: TODO: other cases?
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
 
        @see XStatement
        @see XNamedGraph::getStatements
     */
    com::sun::star::container::XEnumeration/*<XStatement>*/ getStatements(
            [in] XResource Subject,
            [in] XResource Predicate,
            [in] XNode Object)
        raises( com::sun::star::lang::IllegalArgumentException,
                RepositoryException );
 
// Enumeration< XStatement > getStatementsRDFa(s,p,o)
 
 
    //-------------------------------------------------------------------------
    /** 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 QueryException
            if the query string is malformed, or evaluation fails
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
 
        @see XQuerySelectResult
     */
//    Pair<sequence<string>,XRDFIterator<sequence<XNode>>> querySelect([in] string Query)
//    Pair<sequence<string>,com::sun::star::container::XEnumeration/*<sequence<XNode>>*/> querySelect([in] string Query)
    XQuerySelectResult querySelect([in] string Query)
        raises( QueryException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** 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, represented as an
            enumeration of <type>XStatement</type>
 
        @throws QueryException
            if the query string is malformed, or evaluation fails
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
 
        @see XStatement
     */
//    XRDFIterator<XStatement> queryConstruct([in] string Query)
    com::sun::star::container::XEnumeration/*<XStatement>*/ queryConstruct([in] string Query)
        raises( QueryException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** 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 QueryException
            if the query string is malformed, or evaluation fails
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
     */
    boolean queryAsk([in] string Query)
        raises( QueryException,
                RepositoryException );
 
//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 XLiteral(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 XLiteral(RDFaContent^^RDFaDatatype)</li>
            <li>Subject rdfs:label XLiteral(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>
//FIXME: updates???
 
        @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 RDFaDatatype
            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 RepositoryException
            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] XURI Subject,
            [in] XURI Predicate,
            [in] com::sun::star::text::XTextRange Object,
            [in] string RDFaContent,
            [in] string RDFaDatatype)
        raises( com::sun::star::lang::IllegalArgumentException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** 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 RepositoryException
            if an error occurs when accessing the repository.
     */
    void removeStatementRDFa([in] com::sun::star::text::XTextRange Object)
        raises( com::sun::star::lang::IllegalArgumentException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** 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 RepositoryException
            if an error occurs when accessing the repository.
     */
    Pair<XStatement,XStatement> getStatementRDFa(
            [in] XMetadatable Element)
        raises( com::sun::star::lang::IllegalArgumentException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** gets matching RDFa statements from the repository.
 
        <p>
        This method exists because RDFa statements are not part of any named
        graph, and thus they cannot be enumerated with
        <method>XNamedGraph::getStatements</method>.
        </p>
 
        <p>
        Any parameter may be <NULL/>, which acts as a wildcard.
        For example, to get all statements about myURI:
        <code>getStatementsRDFa(myURI, null, null)</code>
        </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 repository that match
            the parameters, represented as an
            enumeration of <type>XStatement</type>
 
        @throws com::sun::star::lang::IllegalArgumentException
            if ... //FIXME: TODO: other cases?
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
 
        @see XStatement
        @see XRepository::getStatements
        @see XNamedGraph::getStatements
     */
    com::sun::star::container::XEnumeration/*<XStatement>*/ getStatementsRDFa(
            [in] XResource Subject,
            [in] XResource Predicate,
            [in] XNode Object)
        raises( com::sun::star::lang::IllegalArgumentException,
                RepositoryException );
 
};
 
 
//=============================================================================
/** provides access to a set of named RDF graphs.
 
    @since OOo 3.0
 
    @see XRepository
    @see XRepositorySupplier
 */
service Repository : XRepository
{
    /** constructs repository with in-memory storage.
     */
    create();
    // FIXME: if we want to support HTTP/SQL-based storage, or inference, define more constructors here
};
 
 
//=============================================================================
/** represents the result of a SPARQL "SELECT" query.
 
    <p>
    The result consists of:
    <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>
    Note that each query result retrieved via
    <method>com::sun::star::container::XEnumeration::nextElement</method>
    has the type
    <type>sequence&lt;XNode&gt;</type>,
    the length of the sequence being the same as the number of query variables. 
    </p>
 
    @since OOo 3.0
 
    @see <method>XRepository::querySelect</method>
    @see XNode
 */
interface XQuerySelectResult : com::sun::star::container::XEnumeration
{
    //-------------------------------------------------------------------------
    /** get the names of the query variables.
 
        <p>
        </p>
     */
     sequence<string> getBindingNames();
};
 
 
//=============================================================================
/** 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 XRepository, w/ graph URI parameter
// but i find it more convenient to have this extra type
// also, it allows inheriting from XNode, with useful semantics:
 
    <p>
    Note that this interface inherits from XResource: 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>XRepository::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 XRepository
 */
interface XNamedGraph : XURI
{
    //-------------------------------------------------------------------------
    /** returns the name of the graph.
 
        <p>
        The name is unique within the repository.
        </p>
 
        @returns
            the name of the graph
     */
    XURI getName();
 
    //-------------------------------------------------------------------------
    /** removes all statements from the graph.
 
        @throws com::sun::star::container::NoSuchElementException
            if this graph does not exist in the repository any more
 
        @throws RepositoryException
            if an error occurs when accessing the repository.
     */
    void clear()
        raises( com::sun::star::container::NoSuchElementException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** 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
        XResource, 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 RepositoryException
            if an error occurs when accessing the repository.
     */
    void addStatement([in] XResource Subject,
            [in] XResource Predicate,
            [in] XNode Object)
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::container::NoSuchElementException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** removes matching RDF statements from the graph.
 
        <p>
        Note that the ODF elements that can have metadata attached all
        implement the interface XMetadatable, which inherits from
        XResource, 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 RepositoryException
            if an error occurs when accessing the repository.
     */
    void removeStatements([in] XResource Subject,
            [in] XResource Predicate,
            [in] XNode Object)
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::container::NoSuchElementException,
                RepositoryException );
 
    //-------------------------------------------------------------------------
    /** gets matching RDF statements from a graph.
 
        <p>
        Note that the ODF elements that can have metadata attached all
        implement the interface XMetadatable, which inherits from
        XResource, 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, represented as an
            enumeration of <type>XStatement</type>
 
        @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 RepositoryException
            if an error occurs when accessing the repository.
 
        @see XStatement
        @see XRepository::getStatements
     */
    com::sun::star::container::XEnumeration/*<XStatement>*/ getStatements(
            [in] XResource Subject,
            [in] XResource Predicate,
            [in] XNode Object)
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::container::NoSuchElementException,
                RepositoryException );
 
//FIXME reification: addReifiedStatement(Statement)...
};
 
 
 
//=============================================================================
/** Constants to specify the MIME types of RDF file formats.
 
    <p>
    These constants are mainly for use with
    <method>XRepository::importGraph</method>
    and <method>XRepository::exportGraph</method>.
    </p>
 
    @since OOo 3.0
 
    @see XRepository
 */
constants FileFormat
{
    /// <a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a>
    const short RDF_XML     = 0;    // "application/rdf+xml";
    // argh! idlc does not even do string constants!
 
    /// <a href="http://www.w3.org/DesignIssues/Notation3">N3 (Notation-3)</a>
    const short N3          = 1;    // "text/rdf+n3";
 
    /// <a href="http://www.w3.org/TR/rdf-testcases/#ntriples">N-Triples</a>
    const short NTRIPLES    = 2;    // "text/plain"; // argh!!!
 
    /// <a href="http://www.wiwiss.fu-berlin.de/suhl/bizer/TriG/Spec/">TriG</a>
    const short TRIG        = 3;    // "application/x-trig";
 
    /// <a href="http://sw.nokia.com/trix/TriX.html">TriX</a>
    const short TRIX        = 4;    // "if only the damn server were up i'd know";
 
    /// <a href="http://www.dajobe.org/2004/01/turtle/">Turtle</a>
    const short TURTLE      = 5;    // "application/turtle";
 
};
 
//=============================================================================
/** Constants to specify some well-known URIs.
 
    <p>
    These constants are mainly for use with
    <method>URI::createKnown</method>
    </p>
 
    @since OOo 3.0
 
    @see URI
 */
constants URIs
{
    /// http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    const short RDF_TYPE    = 0;
    /// http://www.w3.org/2000/01/rdf-schema#label
    const short RDFS_LABEL  = 100;
    /// http://docs.oasis-open.org/opendocument/meta/package/common#hasPart
    const short PKG_HASPART = 1000;
    /// http://docs.oasis-open.org/opendocument/meta/package/common#idref
    const short PKG_IDREF   = 1001;
    /// http://docs.oasis-open.org/opendocument/meta/package/common#path
    const short PKG_PATH    = 1002;
    /// http://docs.oasis-open.org/opendocument/meta/package/common#Package
    const short PKG_PACKAGE = 1003;
    /// http://docs.oasis-open.org/opendocument/meta/package/odf#Element
    const short ODF_ELEMENT         = 2000;
    /// http://docs.oasis-open.org/opendocument/meta/package/odf#ContentFile
    const short ODF_CONTENTFILE     = 2001;
    /// http://docs.oasis-open.org/opendocument/meta/package/odf#StylesFile
    const short ODF_STYLESFILE      = 2002;
    /// http://docs.oasis-open.org/opendocument/meta/package/odf#MetadataFile
    const short ODF_METADATAFILE    = 2003;
};
 
//=============================================================================
/** Constants to specify some useful namespaces.
 
    @since OOo 3.0
 
    @see XRepository
 */
constants RDFNamespaces
{
    //FIXME const structs are not legal IDL
    //FIXME neither are string constants!
    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 XResource.
    </p>
 
    @since OOo 3.0
 
    @see XRepository
 */
//FIXME: inherit from XResource ??? we can call createMapping, or just use the XmlId...
interface XMetadatable : XResource
{
    //-------------------------------------------------------------------------
    /** 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:
    <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 XRepository
 */
 // 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 : XResource
interface XDocumentMetadataAccess : XURI
{
    //-------------------------------------------------------------------------
    /** 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 createMapping(XMetadatable Element);
    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, FIXME: throw or change mapping?
//FIXME: according to the spec, a Element may have multiple URIs!!! (i.e. the spec does not prohibit this)
        </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/>
     */
   // this one uses parameter uri
//    void createMapping([in] XMetadatable Element, [in] XURI URI);
    void createMappingForElement([in] XMetadatable Element, [in] XURI URI)
        raises( com::sun::star::lang::IllegalArgumentException );
 
    //-------------------------------------------------------------------------
    /** removes mapping for an ODF element.
 
        @param Element
            the ODF element for which an URI should be created
 
//FIXME param URI ???
// if mapping is 1-1 then param URI is not necessary; otherwise maybe
 
        @throws com::sun::star::lang::IllegalArgumentException
            if the given Element is <NULL/>
     */
    void removeMappingForElement([in] XMetadatable Element)
        raises( com::sun::star::lang::IllegalArgumentException );
 
    //-------------------------------------------------------------------------
    /** add a metadata file to the manifest.
 
        <p>
        This convenience method does the following:
        <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>
        </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
 
        @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)
        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
 
        @throws com::sun::star::lang::IllegalArgumentException
            if the given GraphName is <NULL/>, 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)
        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 );
 
//FIXME: need add/remvoeContentFile???
    //-------------------------------------------------------------------------
    /** 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.
        If the FileName ends in "content.xml", a ContentFile is added.
        If the FileName ends in "styles.xml" , a StylesFile  is added.
        Other FileNames are invalid.
        </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 );
 
};
 
//=============================================================================
 
}; }; }; };
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.
+ UNO IDL does not allow string constants
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)
+ will probably do this
destroyGraph sounds weird - deleteGraph?
+ destroy is a UNO naming convention
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
+ done
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
+ have modified Statement so it always has Context
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 :-)
+ seems the constructor is needed anyway
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...
Difference between revisions of "Metadata API"

Latest revision as of 12:45, 26 June 2008

Description

API Draft

Comments

Views

Personal tools

Navigation

Search

Tools
