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