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