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

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