offapi/com/sun/star/rdf/XDocumentRepository.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_rdf_XDocumentRepository_idl__
  21 #define __com_sun_star_rdf_XDocumentRepository_idl__
  22
  23 #include <com/sun/star/beans/Pair.idl>
  24 #include <com/sun/star/rdf/XMetadatable.idl>
  25 #include <com/sun/star/rdf/XRepository.idl>
  26
  27
  28
  29 module com {   module sun {   module star {   module rdf {
  30
  31 /** extends XRepository with document-specific functionality.
  32
  33     <p>
  34     This subclass of XRepository provides some methods which
  35     only make sense for repositories that are attached to a document.
  36     For example, the methods allow for manipulating in-content metadata,
  37     which is stored as RDFa.
  38     </p>
  39
  40     @since OOo 3.2
  41
  42     @see XRepositorySupplier
  43     @see XDocumentMetadataAccess
  44  */
  45 interface XDocumentRepository : XRepository
  46 {
  47
  48     /** update the RDFa statement(s) that correspond to an ODF element in the
  49         repository.
  50
  51         <p>
  52         This method will do the following steps:
  53         <ol>
  54         <li>Remove all previously set RDFa statements for the Object parameter
  55              from the repository</li>
  56         <li>If the RDFaContent parameter is the empty `string`,
  57             for every Predicate in the given list of Predicates,
  58             add the following RDF statement to an unspecified named graph:
  59             <ul>
  60             <li><code>Subject Predicate
  61                       XLiteral(Object->getText()^^RDFaDatatype)</code></li>
  62             </ul>
  63         </li>
  64         <li>If the RDFaContent parameter is not the empty `string`,
  65             for every Predicate in the given list of Predicates,
  66             add the following RDF statement to an unspecified named graph:
  67             <ul>
  68             <li>
  69             <code>Subject Predicate XLiteral(RDFaContent^^RDFaDatatype)</code>
  70             </li>
  71             </ul>
  72         </li>
  73         </ol>
  74         </p>
  75
  76         <p>
  77         RDFa statements are handled specially because they are not logically
  78         part of any named graph in the repository.
  79         Also, they have rather unusual semantics;
  80         just using XNamedGraph::addStatement() would be
  81         ambiguous:
  82         if the object is a XMetadatable, do we insert
  83         the object itself (URI) or its literal content (RDFa)?
  84         </p>
  85
  86         @param Subject
  87             the subject of the RDF triple(s).
  88
  89         @param Predicates
  90             the predicates of the RDF triple(s).
  91
  92         @param Object
  93             the object of the RDF triple(s) is the text content of this
  94             parameter.
  95
  96         @param RDFaContent
  97             the <code>rdfa:content</code> attribute (may be the empty
  98             `string`).
  99
 100         @param RDFaDatatype
 101             the <code>rdfa:datatype</code> attribute (may be `NULL`)
 102
 103         @throws com::sun::star::lang::IllegalArgumentException
 104             if any parameter is `NULL`, Predicates is empty,
 105             or Object is of a type that can not have RDFa metadata attached.
 106
 107         @throws RepositoryException
 108             if an error occurs when accessing the repository.
 109      */
 110     void setStatementRDFa(
 111             [in] XResource Subject,
 112             [in] sequence<XURI> Predicates,
 113             [in] XMetadatable Object,
 114             [in] string RDFaContent,
 115             [in] XURI RDFaDatatype)
 116         raises( com::sun::star::lang::IllegalArgumentException,
 117                 RepositoryException );
 118
 119     /** remove the RDFa statement(s) that correspond to an ODF element from the
 120         repository.
 121
 122         <p>
 123         RDFa statements are handled specially because they are not logically
 124         part of any graph.
 125         </p>
 126
 127         @param Element
 128             the element whose RDFa statement(s) should be removed
 129
 130         @throws com::sun::star::lang::IllegalArgumentException
 131             if the given Element is `NULL`, or of a type that can not have
 132             RDFa metadata attached.
 133
 134         @throws RepositoryException
 135             if an error occurs when accessing the repository.
 136      */
 137     void removeStatementRDFa([in] XMetadatable Element)
 138         raises( com::sun::star::lang::IllegalArgumentException,
 139                 RepositoryException );
 140
 141     /** find the RDFa statement(s) associated with an ODF element.
 142
 143         @param Element
 144             the ODF element for which RDFa statements should be found
 145
 146         @returns
 147             <ul>
 148             <li>if the element has no RDFa meta-data attributes:
 149                 the empty sequence.</li>
 150             <li>if the element has RDFa meta-data attributes:
 151                 <ul>
 152                 <li>a sequence with the RDFa-statements corresponding to the
 153                 attributes.</li>
 154                 <li>a flag indicating whether there is a xhtml:content
 155                 attribute.</li>
 156                 </ul>
 157             </li>
 158             </ul>
 159
 160         @throws com::sun::star::lang::IllegalArgumentException
 161             if the given Element is `NULL`, or of a type that can not have
 162             RDFa metadata attached.
 163
 164         @throws RepositoryException
 165             if an error occurs when accessing the repository.
 166
 167         @see Statement
 168      */
 169     com::sun::star::beans::Pair< sequence<Statement>, boolean >
 170             getStatementRDFa([in] XMetadatable Element)
 171         raises( com::sun::star::lang::IllegalArgumentException,
 172                 RepositoryException );
 173
 174     /** gets matching RDFa statements from the repository.
 175
 176         <p>
 177         This method exists because RDFa statements are not part of any named
 178         graph, and thus they cannot be enumerated with
 179         XNamedGraph::getStatements().
 180         </p>
 181
 182         <p>
 183         Any parameter may be `NULL`, which acts as a wildcard.
 184         For example, to get all statements about myURI:
 185         <code>getStatementsRDFa(myURI, null, null)</code>
 186         </p>
 187
 188         @param Subject
 189             the subject of the RDF triple.
 190
 191         @param Predicate
 192             the predicate of the RDF triple.
 193
 194         @param Object
 195             the object of the RDF triple.
 196
 197         @returns
 198             an iterator over all RDFa statements in the repository that match
 199             the parameters, represented as an
 200             enumeration of Statement
 201
 202         @throws RepositoryException
 203             if an error occurs when accessing the repository.
 204
 205         @see Statement
 206         @see XRepository::getStatements
 207         @see XNamedGraph::getStatements
 208      */
 209     com::sun::star::container::XEnumeration/*<Statement>*/ getStatementsRDFa(
 210             [in] XResource Subject,
 211             [in] XURI Predicate,
 212             [in] XNode Object)
 213         raises( RepositoryException );
 214
 215 };
 216
 217
 218 }; }; }; };
 219
 220 #endif
 221
 222 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */