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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_rdf_XRepository_idl__
  21 #define __com_sun_star_rdf_XRepository_idl__
  22
  23 #include <com/sun/star/lang/IllegalArgumentException.idl>
  24 #include <com/sun/star/container/ElementExistException.idl>
  25 #include <com/sun/star/container/NoSuchElementException.idl>
  26 #include <com/sun/star/container/XEnumeration.idl>
  27 #include <com/sun/star/io/IOException.idl>
  28 #include <com/sun/star/io/XInputStream.idl>
  29 #include <com/sun/star/io/XOutputStream.idl>
  30 #include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
  31 #include <com/sun/star/rdf/FileFormat.idl>
  32 #include <com/sun/star/rdf/ParseException.idl>
  33 #include <com/sun/star/rdf/QueryException.idl>
  34 #include <com/sun/star/rdf/RepositoryException.idl>
  35 #include <com/sun/star/rdf/XBlankNode.idl>
  36 #include <com/sun/star/rdf/XURI.idl>
  37 #include <com/sun/star/rdf/Statement.idl>
  38 #include <com/sun/star/rdf/XQuerySelectResult.idl>
  39 #include <com/sun/star/rdf/XNamedGraph.idl>
  40
  41
  42
  43 module com {   module sun {   module star {   module rdf {
  44
  45 /** provides access to a set of named RDF graphs.
  46
  47     <p>
  48     A repository for storing information according to the data model of the
  49     <a href="http://www.w3.org/RDF/">Resource Description Framework</a>.
  50     This interface may be used e.g. for repositories that correspond to a
  51     loaded ODF document, or for repositories that are backed by some kind of
  52     database.
  53     </p>
  54     <p>
  55     The RDF triples are stored as a set of named RDF graphs.
  56     Importing and exporting files in the
  57     <a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a>
  58     format is supported.
  59     Support for other file formats is optional.
  60     Support for querying the repository with the
  61     <a href="http://www.w3.org/TR/rdf-sparql-query/">SPARQL</a>
  62     query language is provided.
  63     </p>
  64
  65
  66     @since OOo 3.2
  67
  68     @see XRepositorySupplier
  69     @see XDocumentRepository
  70  */
  71 interface XRepository
  72 {
  73
  74     /** creates a fresh unique blank node.
  75
  76         @returns
  77             a newly generated blank node which is unique in this repository
  78      */
  79     XBlankNode createBlankNode();
  80
  81
  82     /** imports a named graph into the repository.
  83
  84         <p>
  85         Implementations must support RDF/XML format.
  86         Support for other RDF formats is optional.
  87         If the format is not supported by the implementation, an
  88         com::sun::star::datatransfer::UnsupportedFlavorException is raised.
  89         If the format requires use of a BaseURI, but none is given, an
  90         com::sun::star::lang::IllegalArgumentException
  91         is raised.
  92         </p>
  93
  94         @param Format
  95             the format of the input file
  96
  97         @param InStream
  98             the input stream, containing an RDF file in the specified format
  99
 100         @param GraphName
 101             the name of the graph that is imported
 102
 103         @param BaseURI
 104             a base URI to resolve relative URI references
 105
 106         @returns
 107             the imported graph
 108
 109         @throws com::sun::star::lang::IllegalArgumentException
 110             if the given stream or the GraphName is `NULL`,
 111             or BaseURI is `NULL` and the format requires use of a base URI
 112
 113         @throws com::sun::star::datatransfer::UnsupportedFlavorException
 114             if the format requested is unknown or not supported
 115
 116         @throws com::sun::star::container::ElementExistException
 117             if a graph with the given GraphName already exists in the
 118             repository
 119
 120         @throws ParseException
 121             if the input does not conform to the specified file format.
 122
 123         @throws RepositoryException
 124             if an error occurs when accessing the repository.
 125
 126         @throws com::sun::star::io::IOException
 127             if an I/O error occurs.
 128
 129         @see FileFormat
 130      */
 131     XNamedGraph importGraph([in] /*FileFormat*/ short Format,
 132                 [in] com::sun::star::io::XInputStream InStream,
 133                 [in] XURI GraphName, [in] XURI BaseURI)
 134         raises( com::sun::star::lang::IllegalArgumentException,
 135                 com::sun::star::datatransfer::UnsupportedFlavorException,
 136                 com::sun::star::container::ElementExistException,
 137                 ParseException,
 138                 RepositoryException,
 139                 com::sun::star::io::IOException );
 140
 141     /** exports a named graph from the repository.
 142
 143         <p>
 144         Implementations must support RDF/XML format.
 145         Support for other RDF formats is optional.
 146         If the format is not supported by the implementation, an
 147         com::sun::star::datatransfer::UnsupportedFlavorException is raised.
 148         </p>
 149
 150         @param Format
 151             the format of the output file
 152
 153         @param OutStream
 154             the target output stream
 155
 156         @param GraphName
 157             the name of the graph that is to be exported
 158
 159         @param BaseURI
 160             a base URI to resolve relative URI references
 161
 162         @throws com::sun::star::lang::IllegalArgumentException
 163             if the given stream or the GraphName is `NULL`,
 164             or BaseURI is `NULL` and the format requires use of a base URI
 165
 166         @throws com::sun::star::datatransfer::UnsupportedFlavorException
 167             if the format requested is unknown or not supported
 168
 169         @throws com::sun::star::container::NoSuchElementException
 170             if a graph with the given GraphName does not exist
 171
 172         @throws RepositoryException
 173             if an error occurs when accessing the repository.
 174
 175         @throws com::sun::star::io::IOException
 176             if an I/O error occurs.
 177
 178         @see FileFormat
 179      */
 180     void exportGraph([in] /*FileFormat*/ short Format,
 181                 [in] com::sun::star::io::XOutputStream OutStream,
 182                 [in] XURI GraphName, [in] XURI BaseURI)
 183         raises( com::sun::star::lang::IllegalArgumentException,
 184                 com::sun::star::datatransfer::UnsupportedFlavorException,
 185                 com::sun::star::container::NoSuchElementException,
 186                 RepositoryException,
 187                 com::sun::star::io::IOException );
 188
 189     /** gets the names of all the graphs in the repository.
 190
 191         @returns
 192             a list containing the names of the graphs in the repository
 193
 194         @throws RepositoryException
 195             if an error occurs when accessing the repository.
 196      */
 197     sequence<XURI> getGraphNames()
 198         raises( RepositoryException );
 199
 200     /** gets a graph by its name.
 201
 202         @param GraphName
 203             the name of the graph that is to be returned
 204
 205         @returns
 206             the graph with the given name if it exists, else `NULL`
 207
 208         @throws com::sun::star::lang::IllegalArgumentException
 209             if the given GraphName is invalid
 210
 211         @throws RepositoryException
 212             if an error occurs when accessing the repository.
 213      */
 214     XNamedGraph getGraph([in] XURI GraphName)
 215         raises( com::sun::star::lang::IllegalArgumentException,
 216                 RepositoryException );
 217
 218     /** creates a graph with the given name.
 219
 220         <p>
 221         The name must be unique within the repository.
 222         </p>
 223
 224         @param GraphName
 225             the name of the graph that is to be created
 226
 227         @returns
 228             the graph with the given name
 229
 230         @throws com::sun::star::lang::IllegalArgumentException
 231             if the given GraphName is invalid
 232
 233         @throws com::sun::star::container::ElementExistException
 234             if a graph with the given GraphName already exists
 235
 236         @throws RepositoryException
 237             if an error occurs when accessing the repository.
 238      */
 239     XNamedGraph createGraph([in] XURI GraphName)
 240         raises( com::sun::star::lang::IllegalArgumentException,
 241                 com::sun::star::container::ElementExistException,
 242                 RepositoryException );
 243
 244     /** destroys the graph with the given name, and removes it from the
 245         repository.
 246
 247         <p>
 248         This invalidates any instances of XNamedGraph
 249         for the argument.
 250         </p>
 251
 252         @param GraphName
 253             the name of the graph that is to be destroyed
 254
 255         @throws com::sun::star::lang::IllegalArgumentException
 256             if the given GraphName is invalid
 257
 258         @throws com::sun::star::container::NoSuchElementException
 259             if a graph with the given GraphName does not exist
 260
 261         @throws RepositoryException
 262             if an error occurs when accessing the repository.
 263      */
 264     void destroyGraph([in] XURI GraphName)
 265         raises( com::sun::star::lang::IllegalArgumentException,
 266                 com::sun::star::container::NoSuchElementException,
 267                 RepositoryException );
 268
 269     /** gets matching RDF statements from the repository.
 270
 271         <p>
 272         Any parameter may be `NULL`, which acts as a wildcard.
 273         For example, to get all statements about myURI:
 274         <code>getStatements(myURI, null, null)</code>
 275         </p>
 276
 277         @param Subject
 278             the subject of the RDF triple.
 279
 280         @param Predicate
 281             the predicate of the RDF triple.
 282
 283         @param Object
 284             the object of the RDF triple.
 285
 286         @returns
 287             an iterator over all RDF statements in the repository that match
 288             the parameters, represented as an
 289             enumeration of Statement
 290
 291         @throws RepositoryException
 292             if an error occurs when accessing the repository.
 293
 294         @see Statement
 295         @see XNamedGraph::getStatements
 296      */
 297     com::sun::star::container::XEnumeration/*<Statement>*/ getStatements(
 298             [in] XResource Subject,
 299             [in] XURI Predicate,
 300             [in] XNode Object)
 301         raises( RepositoryException );
 302
 303
 304     /** executes a SPARQL "SELECT" query.
 305
 306         <p>
 307         This method runs a SPARQL query that returns a list of variable
 308         bindings, i.e., a query beginning with "SELECT".
 309         The result is basically a (rectangular) table with labeled columns,
 310         where individual cells may be `NULL`.
 311         </p>
 312
 313         @param Query
 314             the SPARQL query `string`
 315
 316         @returns
 317             an enumeration, containing
 318             <ol>
 319             <li>a list of query variable names (column labels)</li>
 320             <li>the query results (rows),
 321                 each being a list of bindings for the above variables</li>
 322             </ol>
 323
 324         @throws QueryException
 325             if the query is malformed, or evaluation fails
 326
 327         @throws RepositoryException
 328             if an error occurs when accessing the repository.
 329
 330         @see XQuerySelectResult
 331      */
 332     XQuerySelectResult querySelect([in] string Query)
 333         raises( QueryException,
 334                 RepositoryException );
 335
 336     /** executes a SPARQL "CONSTRUCT" query.
 337
 338         <p>
 339         This method runs a SPARQL query that constructs a result graph,
 340         i.e., a query beginning with "CONSTRUCT".
 341         </p>
 342
 343         @param Query
 344             the SPARQL query `string`
 345
 346         @returns
 347             an iterator over the query result graph, represented as an
 348             enumeration of Statement
 349
 350         @throws QueryException
 351             if the query is malformed, or evaluation fails
 352
 353         @throws RepositoryException
 354             if an error occurs when accessing the repository.
 355
 356         @see Statement
 357      */
 358     com::sun::star::container::XEnumeration/*<Statement>*/ queryConstruct(
 359             [in] string Query)
 360         raises( QueryException,
 361                 RepositoryException );
 362
 363     /** executes a SPARQL "ASK" query.
 364
 365         <p>
 366         This method runs a SPARQL query that computes a boolean,
 367         i.e., a query beginning with "ASK".
 368         </p>
 369
 370         @param Query
 371             the SPARQL query `string`
 372
 373         @returns
 374             the boolean query result
 375
 376         @throws QueryException
 377             if the query is malformed, or evaluation fails
 378
 379         @throws RepositoryException
 380             if an error occurs when accessing the repository.
 381      */
 382     boolean queryAsk([in] string Query)
 383         raises( QueryException,
 384                 RepositoryException );
 385
 386 };
 387
 388
 389 }; }; }; };
 390
 391 #endif
 392
 393 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */