Metadata API
From Apache OpenOffice Wiki
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<XNode></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...
