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
46module 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 */
63interface 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
244