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