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

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