xref: /aoo42x/main/offapi/com/sun/star/rdf/XRepository.idl (revision 96af39f7)
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_XRepository_idl__
25#define __com_sun_star_rdf_XRepository_idl__
26
27#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
28#include <com/sun/star/lang/IllegalArgumentException.idl>
29#endif
30
31#ifndef __com_sun_star_container_ElementExistException_idl__
32#include <com/sun/star/container/ElementExistException.idl>
33#endif
34
35#ifndef __com_sun_star_container_NoSuchElementException_idl__
36#include <com/sun/star/container/NoSuchElementException.idl>
37#endif
38
39#ifndef __com_sun_star_container_XEnumeration_idl__
40#include <com/sun/star/container/XEnumeration.idl>
41#endif
42
43#ifndef __com_sun_star_io_IOException_idl__
44#include <com/sun/star/io/IOException.idl>
45#endif
46
47#ifndef __com_sun_star_io_XInputStream_idl__
48#include <com/sun/star/io/XInputStream.idl>
49#endif
50
51#ifndef __com_sun_star_io_XOutputStream_idl__
52#include <com/sun/star/io/XOutputStream.idl>
53#endif
54
55#ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__
56#include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
57#endif
58
59#ifndef __com_sun_star_rdf_FileFormat_idl__
60#include <com/sun/star/rdf/FileFormat.idl>
61#endif
62
63#ifndef __com_sun_star_rdf_ParseException_idl__
64#include <com/sun/star/rdf/ParseException.idl>
65#endif
66
67#ifndef __com_sun_star_rdf_QueryException_idl__
68#include <com/sun/star/rdf/QueryException.idl>
69#endif
70
71#ifndef __com_sun_star_rdf_RepositoryException_idl__
72#include <com/sun/star/rdf/RepositoryException.idl>
73#endif
74
75#ifndef __com_sun_star_rdf_XBlankNode_idl__
76#include <com/sun/star/rdf/XBlankNode.idl>
77#endif
78
79#ifndef __com_sun_star_rdf_XURI_idl__
80#include <com/sun/star/rdf/XURI.idl>
81#endif
82
83#ifndef __com_sun_star_rdf_Statement_idl__
84#include <com/sun/star/rdf/Statement.idl>
85#endif
86
87#ifndef __com_sun_star_rdf_XQuerySelectResult_idl__
88#include <com/sun/star/rdf/XQuerySelectResult.idl>
89#endif
90
91#ifndef __com_sun_star_rdf_XNamedGraph_idl__
92#include <com/sun/star/rdf/XNamedGraph.idl>
93#endif
94
95
96//=============================================================================
97
98module com {   module sun {   module star {   module rdf {
99
100//=============================================================================
101/** provides access to a set of named RDF graphs.
102
103    <p>
104    A repository for storing information according to the data model of the
105    <a href="http://www.w3.org/RDF/">Resource Description Framework</a>.
106    This interface may be used e.g. for repositories that correspond to a
107    loaded ODF document, or for repositories that are backed by some kind of
108    database.
109    </p>
110    <p>
111    The RDF triples are stored as a set of named RDF graphs.
112    Importing and exporting files in the
113    <a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a>
114    format is supported.
115    Support for other file formats is optional.
116    Support for querying the repository with the
117    <a href="http://www.w3.org/TR/rdf-sparql-query/">SPARQL</a>
118    query language is provided.
119    </p>
120
121
122    @since OpenOffice 3.2
123
124    @see XRepositorySupplier
125    @see XDocumentRepository
126 */
127interface XRepository
128{
129
130    //-------------------------------------------------------------------------
131    /** creates a fresh unique blank node.
132
133        @returns
134            a newly generated blank node which is unique in this repository
135     */
136    XBlankNode createBlankNode();
137
138
139    //-------------------------------------------------------------------------
140    /** imports a named graph into the repository.
141
142        <p>
143        Implementations must support RDF/XML format.
144        Support for other RDF formats is optional.
145        If the format is not supported by the implementation, an
146        <type scope="com::sun::star::datatransfer">UnsupportedFlavorException
147        </type> is raised.
148        If the format requires use of a BaseURI, but none is given, an
149        <type scope="com::sun::star::lang">IllegalArgumentException</type>
150        is raised.
151        </p>
152
153        @param Format
154            the format of the input file
155
156        @param InStream
157            the input stream, containing an RDF file in the specified format
158
159        @param GraphName
160            the name of the graph that is imported
161
162        @param BaseURI
163            a base URI to resolve relative URI references
164
165        @returns
166            the imported graph
167
168        @throws com::sun::star::lang::IllegalArgumentException
169            if the given stream or the GraphName is <NULL/>,
170            or BaseURI is <NULL/> and the format requires use of a base URI
171
172        @throws com::sun::star::datatransfer::UnsupportedFlavorException
173            if the format requested is unknown or not supported
174
175        @throws com::sun::star::container::ElementExistException
176            if a graph with the given GraphName already exists in the
177            repository
178
179        @throws ParseException
180            if the input does not conform to the specified file format.
181
182        @throws RepositoryException
183            if an error occurs when accessing the repository.
184
185        @throws com::sun::star::io::IOException
186            if an I/O error occurs.
187
188        @see FileFormat
189     */
190    XNamedGraph importGraph([in] /*FileFormat*/ short Format,
191                [in] com::sun::star::io::XInputStream InStream,
192                [in] XURI GraphName, [in] XURI BaseURI)
193        raises( com::sun::star::lang::IllegalArgumentException,
194                com::sun::star::datatransfer::UnsupportedFlavorException,
195                com::sun::star::container::ElementExistException,
196                ParseException,
197                RepositoryException,
198                com::sun::star::io::IOException );
199
200    //-------------------------------------------------------------------------
201    /** exports a named graph from the repository.
202
203        <p>
204        Implementations must support RDF/XML format.
205        Support for other RDF formats is optional.
206        If the format is not supported by the implementation, an
207        <type scope="com::sun::star::datatransfer">UnsupportedFlavorException
208        </type> is raised.
209        </p>
210
211        @param Format
212            the format of the output file
213
214        @param OutStream
215            the target output stream
216
217        @param GraphName
218            the name of the graph that is to be exported
219
220        @param BaseURI
221            a base URI to resolve relative URI references
222
223        @throws com::sun::star::lang::IllegalArgumentException
224            if the given stream or the GraphName is <NULL/>,
225            or BaseURI is <NULL/> and the format requires use of a base URI
226
227        @throws com::sun::star::datatransfer::UnsupportedFlavorException
228            if the format requested is unknown or not supported
229
230        @throws com::sun::star::container::NoSuchElementException
231            if a graph with the given GraphName does not exist
232
233        @throws RepositoryException
234            if an error occurs when accessing the repository.
235
236        @throws com::sun::star::io::IOException
237            if an I/O error occurs.
238
239        @see FileFormat
240     */
241    void exportGraph([in] /*FileFormat*/ short Format,
242                [in] com::sun::star::io::XOutputStream OutStream,
243                [in] XURI GraphName, [in] XURI BaseURI)
244        raises( com::sun::star::lang::IllegalArgumentException,
245                com::sun::star::datatransfer::UnsupportedFlavorException,
246                com::sun::star::container::NoSuchElementException,
247                RepositoryException,
248                com::sun::star::io::IOException );
249
250    //-------------------------------------------------------------------------
251    /** gets the names of all the graphs in the repository.
252
253        @returns
254            a list containing the names of the graphs in the repository
255
256        @throws RepositoryException
257            if an error occurs when accessing the repository.
258     */
259    sequence<XURI> getGraphNames()
260        raises( RepositoryException );
261
262    //-------------------------------------------------------------------------
263    /** gets a graph by its name.
264
265        @param GraphName
266            the name of the graph that is to be returned
267
268        @returns
269            the graph with the given name if it exists, else <NULL/>
270
271        @throws com::sun::star::lang::IllegalArgumentException
272            if the given GraphName is invalid
273
274        @throws RepositoryException
275            if an error occurs when accessing the repository.
276     */
277    XNamedGraph getGraph([in] XURI GraphName)
278        raises( com::sun::star::lang::IllegalArgumentException,
279                RepositoryException );
280
281    //-------------------------------------------------------------------------
282    /** creates a graph with the given name.
283
284        <p>
285        The name must be unique within the repository.
286        </p>
287
288        @param GraphName
289            the name of the graph that is to be created
290
291        @returns
292            the graph with the given name
293
294        @throws com::sun::star::lang::IllegalArgumentException
295            if the given GraphName is invalid
296
297        @throws com::sun::star::container::ElementExistException
298            if a graph with the given GraphName already exists
299
300        @throws RepositoryException
301            if an error occurs when accessing the repository.
302     */
303    XNamedGraph createGraph([in] XURI GraphName)
304        raises( com::sun::star::lang::IllegalArgumentException,
305                com::sun::star::container::ElementExistException,
306                RepositoryException );
307
308    //-------------------------------------------------------------------------
309    /** destroys the graph with the given name, and removes it from the
310        repository.
311
312        <p>
313        This invalidates any instances of <type>XNamedGraph</type>
314        for the argument.
315        </p>
316
317        @param GraphName
318            the name of the graph that is to be destroyed
319
320        @throws com::sun::star::lang::IllegalArgumentException
321            if the given GraphName is invalid
322
323        @throws com::sun::star::container::NoSuchElementException
324            if a graph with the given GraphName does not exist
325
326        @throws RepositoryException
327            if an error occurs when accessing the repository.
328     */
329    void destroyGraph([in] XURI GraphName)
330        raises( com::sun::star::lang::IllegalArgumentException,
331                com::sun::star::container::NoSuchElementException,
332                RepositoryException );
333
334    //-------------------------------------------------------------------------
335    /** gets matching RDF statements from the repository.
336
337        <p>
338        Any parameter may be <NULL/>, which acts as a wildcard.
339        For example, to get all statements about myURI:
340        <code>getStatements(myURI, null, null)</code>
341        </p>
342
343        @param Subject
344            the subject of the RDF triple.
345
346        @param Predicate
347            the predicate of the RDF triple.
348
349        @param Object
350            the object of the RDF triple.
351
352        @returns
353            an iterator over all RDF statements in the repository that match
354            the parameters, represented as an
355            enumeration of <type>Statement</type>
356
357        @throws RepositoryException
358            if an error occurs when accessing the repository.
359
360        @see Statement
361        @see XNamedGraph::getStatements
362     */
363    com::sun::star::container::XEnumeration/*<Statement>*/ getStatements(
364            [in] XResource Subject,
365            [in] XURI Predicate,
366            [in] XNode Object)
367        raises( RepositoryException );
368
369
370    //-------------------------------------------------------------------------
371    /** executes a SPARQL "SELECT" query.
372
373        <p>
374        This method runs a SPARQL query that returns a list of variable
375        bindings, i.e., a query beginning with "SELECT".
376        The result is basically a (rectangular) table with labeled columns,
377        where individual cells may be <NULL/>.
378        </p>
379
380        @param Query
381            the SPARQL query <atom>string</atom>
382
383        @returns
384            an enumeration, containing
385            <ol>
386            <li>a list of query variable names (column labels)</li>
387            <li>the query results (rows),
388                each being a list of bindings for the above variables</li>
389            </ol>
390
391        @throws QueryException
392            if the query is malformed, or evaluation fails
393
394        @throws RepositoryException
395            if an error occurs when accessing the repository.
396
397        @see XQuerySelectResult
398     */
399    XQuerySelectResult querySelect([in] string Query)
400        raises( QueryException,
401                RepositoryException );
402
403    //-------------------------------------------------------------------------
404    /** executes a SPARQL "CONSTRUCT" query.
405
406        <p>
407        This method runs a SPARQL query that constructs a result graph,
408        i.e., a query beginning with "CONSTRUCT".
409        </p>
410
411        @param Query
412            the SPARQL query <atom>string</atom>
413
414        @returns
415            an iterator over the query result graph, represented as an
416            enumeration of <type>Statement</type>
417
418        @throws QueryException
419            if the query is malformed, or evaluation fails
420
421        @throws RepositoryException
422            if an error occurs when accessing the repository.
423
424        @see Statement
425     */
426    com::sun::star::container::XEnumeration/*<Statement>*/ queryConstruct(
427            [in] string Query)
428        raises( QueryException,
429                RepositoryException );
430
431    //-------------------------------------------------------------------------
432    /** executes a SPARQL "ASK" query.
433
434        <p>
435        This method runs a SPARQL query that computes a boolean,
436        i.e., a query beginning with "ASK".
437        </p>
438
439        @param Query
440            the SPARQL query <atom>string</atom>
441
442        @returns
443            the boolean query result
444
445        @throws QueryException
446            if the query is malformed, or evaluation fails
447
448        @throws RepositoryException
449            if an error occurs when accessing the repository.
450     */
451    boolean queryAsk([in] string Query)
452        raises( QueryException,
453                RepositoryException );
454
455};
456
457//=============================================================================
458
459}; }; }; };
460
461#endif
462