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

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