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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef __com_sun_star_rdf_XDocumentRepository_idl__
  29 #define __com_sun_star_rdf_XDocumentRepository_idl__
  30
  31 #ifndef __com_sun_star_beans_Pair_idl__
  32 #include <com/sun/star/beans/Pair.idl>
  33 #endif
  34
  35 #ifndef __com_sun_star_rdf_XMetadatable_idl__
  36 #include <com/sun/star/rdf/XMetadatable.idl>
  37 #endif
  38
  39 #ifndef __com_sun_star_rdf_XRepository_idl__
  40 #include <com/sun/star/rdf/XRepository.idl>
  41 #endif
  42
  43
  44 //=============================================================================
  45
  46 module com {   module sun {   module star {   module rdf {
  47
  48 //=============================================================================
  49 /** extends <type>XRepository</type> with document-specific functionality.
  50
  51     <p>
  52     This subclass of <type>XRepository</type> provides some methods which
  53     only make sense for repositories that are attached to a document.
  54     For example, the methods allow for manipulating in-content metadata,
  55     which is stored as RDFa.
  56     </p>
  57
  58     @since OOo 3.2
  59
  60     @see XRepositorySupplier
  61     @see XDocumentMetadataAccess
  62  */
  63 interface XDocumentRepository : XRepository
  64 {
  65
  66     //-------------------------------------------------------------------------
  67     /** update the RDFa statement(s) that correspond to an ODF element in the
  68         repository.
  69
  70         <p>
  71         This method will do the following steps:
  72         <ol>
  73         <li>Remove all previously set RDFa statements for the Object parameter
  74              from the repository</li>
  75         <li>If the RDFaContent parameter is the empty <atom>string</atom>,
  76             for every Predicate in the given list of Predicates,
  77             add the following RDF statement to an unspecified named graph:
  78             <ul>
  79             <li><code>Subject Predicate
  80                       XLiteral(Object->getText()^^RDFaDatatype)</code></li>
  81             </ul>
  82         </li>
  83         <li>If the RDFaContent parameter is not the empty <atom>string</atom>,
  84             for every Predicate in the given list of Predicates,
  85             add the following RDF statement to an unspecified named graph:
  86             <ul>
  87             <li>
  88             <code>Subject Predicate XLiteral(RDFaContent^^RDFaDatatype)</code>
  89             </li>
  90             </ul>
  91         </li>
  92         </ol>
  93         </p>
  94
  95         <p>
  96         RDFa statements are handled specially because they are not logically
  97         part of any named graph in the repository.
  98         Also, they have rather unusual semantics;
  99         just using <member>XNamedGraph::addStatement</member> would be
 100         ambiguous:
 101         if the object is a <type>XMetadatable</type>, do we insert
 102         the object itself (URI) or its literal content (RDFa)?
 103         </p>
 104
 105         @param Subject
 106             the subject of the RDF triple(s).
 107
 108         @param Predicates
 109             the predicates of the RDF triple(s).
 110
 111         @param Object
 112             the object of the RDF triple(s) is the text content of this
 113             parameter.
 114
 115         @param RDFaContent
 116             the <code>rdfa:content</code> attribute (may be the empty
 117             <atom>string</atom>).
 118
 119         @param RDFaDatatype
 120             the <code>rdfa:datatype</code> attribute (may be <NULL/>)
 121
 122         @throws com::sun::star::lang::IllegalArgumentException
 123             if any parameter is <NULL/>, Predicates is empty,
 124             or Object is of a type that can not have RDFa metadata attached.
 125
 126         @throws RepositoryException
 127             if an error occurs when accessing the repository.
 128      */
 129     void setStatementRDFa(
 130             [in] XResource Subject,
 131             [in] sequence<XURI> Predicates,
 132             [in] XMetadatable Object,
 133             [in] string RDFaContent,
 134             [in] XURI RDFaDatatype)
 135         raises( com::sun::star::lang::IllegalArgumentException,
 136                 RepositoryException );
 137
 138     //-------------------------------------------------------------------------
 139     /** remove the RDFa statement(s) that correspond to an ODF element from the
 140         repository.
 141
 142         <p>
 143         RDFa statements are handled specially because they are not logically
 144         part of any graph.
 145         </p>
 146
 147         @param Element
 148             the element whose RDFa statement(s) should be removed
 149
 150         @throws com::sun::star::lang::IllegalArgumentException
 151             if the given Element is <NULL/>, or of a type that can not have
 152             RDFa metadata attached.
 153
 154         @throws RepositoryException
 155             if an error occurs when accessing the repository.
 156      */
 157     void removeStatementRDFa([in] XMetadatable Element)
 158         raises( com::sun::star::lang::IllegalArgumentException,
 159                 RepositoryException );
 160
 161     //-------------------------------------------------------------------------
 162     /** find the RDFa statement(s) associated with an ODF element.
 163
 164         @param Element
 165             the ODF element for which RDFa statements should be found
 166
 167         @returns
 168             <ul>
 169             <li>if the element has no RDFa meta-data attributes:
 170                 the empty sequence.</li>
 171             <li>if the element has RDFa meta-data attributes:
 172                 <ul>
 173                 <li>a sequence with the RDFa-statements corresponding to the
 174                 attributes.</li>
 175                 <li>a flag indicating whether there is a xhtml:content
 176                 attribute.</li>
 177                 </ul>
 178             </li>
 179             </ul>
 180
 181         @throws com::sun::star::lang::IllegalArgumentException
 182             if the given Element is <NULL/>, or of a type that can not have
 183             RDFa metadata attached.
 184
 185         @throws RepositoryException
 186             if an error occurs when accessing the repository.
 187
 188         @see Statement
 189      */
 190     com::sun::star::beans::Pair< sequence<Statement>, boolean >
 191             getStatementRDFa([in] XMetadatable Element)
 192         raises( com::sun::star::lang::IllegalArgumentException,
 193                 RepositoryException );
 194
 195     //-------------------------------------------------------------------------
 196     /** gets matching RDFa statements from the repository.
 197
 198         <p>
 199         This method exists because RDFa statements are not part of any named
 200         graph, and thus they cannot be enumerated with
 201         <member>XNamedGraph::getStatements</member>.
 202         </p>
 203
 204         <p>
 205         Any parameter may be <NULL/>, which acts as a wildcard.
 206         For example, to get all statements about myURI:
 207         <code>getStatementsRDFa(myURI, null, null)</code>
 208         </p>
 209
 210         @param Subject
 211             the subject of the RDF triple.
 212
 213         @param Predicate
 214             the predicate of the RDF triple.
 215
 216         @param Object
 217             the object of the RDF triple.
 218
 219         @returns
 220             an iterator over all RDFa statements in the repository that match
 221             the parameters, represented as an
 222             enumeration of <type>Statement</type>
 223
 224         @throws RepositoryException
 225             if an error occurs when accessing the repository.
 226
 227         @see Statement
 228         @see XRepository::getStatements
 229         @see XNamedGraph::getStatements
 230      */
 231     com::sun::star::container::XEnumeration/*<Statement>*/ getStatementsRDFa(
 232             [in] XResource Subject,
 233             [in] XURI Predicate,
 234             [in] XNode Object)
 235         raises( RepositoryException );
 236
 237 };
 238
 239 //=============================================================================
 240
 241 }; }; }; };
 242
 243 #endif