offapi/com/sun/star/sdbc/XConnection.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  module com {  module sun {  module star {  module container {
  21  published interface XNameAccess;
  22 };};};};
  23
  24  module com {  module sun {  module star {  module sdbc {
  25
  26  published interface XStatement;
  27  published interface XPreparedStatement;
  28  published interface XDatabaseMetaData;
  29
  30
  31 /** represents a connection (session) with a specific
  32     database. Within the context of a Connection, SQL statements are
  33     executed and results are returned.
  34
  35
  36     <p>
  37     A Connection's database is able to provide information
  38     describing its tables, its supported SQL grammar, its stored
  39     procedures, and the capabilities of this connection. This
  40     information is obtained with the
  41     com::sun::star::sdbc::XDatabaseMetaData::getMetaData()
  42     method.
  43
  44     </p>
  45     @see com::sun::star::sdbc::XDriverManager
  46     @see com::sun::star::sdbc::XStatement
  47     @see com::sun::star::sdbc::XDatabaseMetaData
  48  */
  49 published interface XConnection: com::sun::star::sdbc::XCloseable
  50 {
  51
  52     /** creates a new
  53         com::sun::star::sdbc::Statement
  54         object for sending SQL statements to the database.
  55
  56
  57         <p>
  58         SQL statements without parameters are normally
  59         executed using Statement objects. If the same SQL statement
  60         is executed many times, it is more efficient to use a
  61         com::sun::star::sdbc::PreparedStatement.
  62         </p>
  63         <p>
  64         Result sets created using the returned Statement will have
  65         forward-only type, and read-only concurrency, by default.
  66         </p>
  67         <p>
  68         Escape processing for the SQL-Statement is enabled, by default.
  69         </p>
  70
  71         @returns
  72             a new Statement object
  73         @throws SQLException
  74             if a database access error occurs.
  75      */
  76     XStatement createStatement() raises (SQLException);
  77
  78     /** creates a
  79         com::sun::star::sdbc::PreparedStatement
  80         object for sending parameterized SQL statements to the database.
  81
  82
  83         <p>
  84         A SQL statement with or without IN parameters can be
  85         pre-compiled and stored in a PreparedStatement object. This
  86         object can then be used to efficiently execute this statement
  87         multiple times.
  88
  89         </p>
  90         <p>
  91         <b>
  92         Note:
  93         </b>
  94         This method is optimized for handling
  95         parametric SQL statements that benefit from precompilation. If
  96         the driver supports precompilation,
  97         the method
  98         <code>prepareStatement</code>
  99         will send
 100         the statement to the database for precompilation. Some drivers
 101         may not support precompilation. In this case, the statement may
 102         not be sent to the database until the
 103         com::sun::star::sdbc::PreparedStatement
 104         is executed.  This has no direct effect on users; however, it does
 105         affect which method throws certain SQLExceptions.
 106         </p>
 107         <p>
 108         Result sets created using the returned PreparedStatement will have
 109         forward-only type and read-only concurrency, by default.
 110         </p>
 111         <p>
 112         Escape processing for the SQL-Statement is enabled, by default.
 113         </p>
 114
 115         @param sql
 116             a SQL statement that may contain one or more "?" IN parameter placeholders
 117         @returns
 118             a new PreparedStatement object containing the pre-compiled statement
 119         @throws SQLException
 120             if a database access error occurs.
 121      */
 122     XPreparedStatement prepareStatement([in]string sql) raises (SQLException);
 123
 124     /** creates a
 125         com::sun::star::sdbc::CallableStatement
 126         object for calling
 127         database stored procedures.
 128
 129
 130         <p>
 131         The CallableStatement provides methods for setting up its IN and OUT
 132         parameters, and methods for executing the call to a stored procedure.
 133         </p>
 134         <p>
 135         <b>
 136         Note:
 137         </b>
 138         This method is optimized for handling stored
 139         procedure call statements. Some drivers may send the call
 140         statement to the database when the method
 141         <code>prepareCall</code>
 142         is done;
 143         <br/>
 144         others may wait until the CallableStatement is executed. This has no
 145         direct effect on users; however, it does affect which method
 146         throws certain SQLExceptions.
 147         Result sets created using the returned CallableStatement will have
 148         forward-only type and read-only concurrency, by default.
 149         </p>
 150
 151         @param sql
 152             a SQL statement that may contain one or more "?" IN parameter placeholders
 153         @returns
 154             a new PreparedStatement object containing the pre-compiled statement
 155         @throws SQLException
 156             if a database access error occurs.
 157      */
 158     XPreparedStatement prepareCall([in]string sql) raises (SQLException);
 159
 160     /** converts the given SQL statement into the system's native SQL grammar.
 161         A driver may convert the JDBC SQL grammar into its system's
 162         native SQL grammar prior to sending it; this method returns the
 163         native form of the statement that the driver would have sent.
 164
 165         @param sql
 166             a SQL statement that may contain one or more "?" parameter placeholders
 167         @returns
 168             the native form of this statement
 169         @throws SQLException
 170             if a database access error occurs.
 171      */
 172     string nativeSQL([in]string sql) raises (SQLException);
 173
 174     /** sets this connection's auto-commit mode.
 175
 176
 177         <p>
 178         If a connection is in auto-commit mode, then all its SQL
 179         statements will be executed and committed as individual
 180         transactions. Otherwise, its SQL statements are grouped into
 181         transactions that are terminated by a call to either
 182         the method
 183         com::sun::star::sdbc::XConnection::commit()
 184         or the method
 185         com::sun::star::sdbc::XConnection::rollback().
 186         By default, new connections are in auto-commit mode.
 187         </p>
 188         <p>
 189         The commit occurs when the statement completes or the next
 190         execute occurs, whichever comes first. In the case of
 191         statements returning a ResultSet, the statement completes when
 192         the last row of the ResultSet has been retrieved or the
 193         ResultSet has been closed. In advanced cases, a single
 194         statement may return multiple results as well as output
 195         parameter values. In these cases the commit occurs when all results and
 196         output parameter values have been retrieved.
 197         </p>
 198
 199         @param autoCommit
 200             `TRUE` enables auto-commit; `FALSE` disables auto-commit.
 201         @throws SQLException
 202             if a database access error occurs.
 203      */
 204     void setAutoCommit([in] boolean autoCommit) raises (SQLException);
 205
 206     /** gets the current auto-commit state.
 207
 208         @returns
 209             the current state of auto-commit mode.
 210         @throws SQLException
 211             if a database access error occurs.
 212
 213         @see setAutoCommit
 214      */
 215     boolean getAutoCommit() raises (SQLException);
 216
 217     /** makes all changes made since the previous commit/rollback
 218         permanent and releases any database locks currently held
 219         by the Connection. This method should be
 220         used only when auto-commit mode has been disabled.
 221
 222         @throws SQLException
 223             if a database access error occurs.
 224
 225         @see setAutoCommit
 226      */
 227     void commit() raises (SQLException);
 228
 229     /** drops all changes made since the previous
 230         commit/rollback and releases any database locks currently held
 231         by this Connection. This method should be used only when auto-commit has been disabled.
 232
 233         @throws SQLException
 234             if a database access error occurs.
 235
 236         @see setAutoCommit
 237      */
 238     void rollback() raises (SQLException);
 239
 240     /** tests to see if a connection is closed.
 241
 242
 243         <p>
 244         <b>
 245         Note:
 246         </b>
 247         A Connection is automatically closed if no one references it
 248         anymore. Certain fatal errors also result in a closed Connection.
 249         </p>
 250
 251         @returns
 252             `TRUE` if the connection is closed; `FALSE` if it's still open.
 253         @throws SQLException
 254             if a database access error occurs.
 255      */
 256     boolean isClosed() raises (SQLException);
 257
 258     /** gets the metadata regarding this connection's database.
 259
 260
 261         <p>
 262         A Connection's database is able to provide information
 263         describing its tables, its supported SQL grammar, its stored
 264         procedures, the capabilities of this connection, and so on. This
 265         information is made available through a DatabaseMetaData
 266         object.
 267         </p>
 268
 269         @returns
 270             a DatabaseMetaData object for this Connection.
 271         @throws SQLException
 272             if a database access error occurs.
 273      */
 274     XDatabaseMetaData getMetaData() raises (SQLException);
 275
 276     /** puts this connection in read-only mode as a hint to enable
 277         database optimizations.
 278
 279
 280         <p>
 281         <b>
 282         Note:
 283         </b>
 284         This method cannot be called while in the
 285         middle of a transaction. Calling setReadOnly with
 286         `TRUE`
 287         does not
 288         necessarily cause writes to be prohibited.
 289         </p>
 290
 291         @param readOnly
 292             `TRUE` enables read-only mode; `FALSE` disables read-only mode.
 293         @throws SQLException
 294             if a database access error occurs.
 295      */
 296     void setReadOnly([in]boolean readOnly) raises (SQLException);
 297
 298     /** tests to see if the connection is in read-only mode.
 299         @returns
 300             `TRUE` if connection is read-only and `FALSE` otherwise.
 301         @throws SQLException
 302             if a database access error occurs.
 303      */
 304     boolean isReadOnly() raises (SQLException);
 305
 306     /** sets a catalog name in order to select
 307         a subspace of this Connection's database in which to work.
 308         If the driver does not support catalogs, it will
 309         silently ignore this request.
 310         @param catalog
 311             the name of the catalog.
 312         @throws SQLException
 313             if a database access error occurs.
 314      */
 315     void setCatalog([in]string catalog) raises (SQLException);
 316
 317     /** returns the Connection's current catalog name.
 318         @returns
 319             the current catalog name or an empty string.
 320         @throws SQLException
 321             if a database access error occurs.
 322      */
 323     string getCatalog() raises (SQLException);
 324
 325     /** attempts to change the transaction isolation level to the one given.
 326
 327
 328         <p>
 329         The constants defined in
 330         com::sun::star::sdbc::TransactionIsolation
 331         are the possible transaction isolation levels.
 332         </p>
 333         <p>
 334         <b>
 335         Note:
 336         </b>
 337         This method cannot be called while
 338         in the middle of a transaction.
 339         </p>
 340         @param level
 341             one of the TransactionIsolation values with the exception of NONE; some databases may not support other values.
 342         @throws SQLException
 343             if a database access error occurs.
 344
 345         @see com::sun::star::sdbc::XDatabaseMetaData::supportsTransactionIsolationLevel()
 346      */
 347     void setTransactionIsolation([in]long level) raises (SQLException);
 348
 349     /** gets this Connection's current transaction isolation level.
 350         @returns
 351             the current TransactionIsolation mode value.
 352         @throws SQLException
 353             if a database access error occurs.
 354      */
 355     long getTransactionIsolation() raises (SQLException);
 356
 357     /** gets the type map object associated with this connection. Only drivers
 358         which implement the custom type mapping facility will return an object otherwise
 359         NULL could be returned.
 360
 361         <p>
 362         Unless the application has added an entry to the type map, the map
 363         returned will be empty.
 364         </p>
 365         @returns
 366             the XNameAccess object associated with this Connection object.
 367
 368         @throws SQLException
 369             if a database access error occurs.
 370      */
 371     com::sun::star::container::XNameAccess getTypeMap() raises (SQLException);
 372
 373     /** installs the given type map as the type map for this connection.
 374         The type map will be used for the custom mapping of SQL structured types
 375         and distinct types.
 376
 377
 378         <p>
 379         Only if the driver supports custom type mapping is the setting of a map allowed.
 380         </p>
 381
 382         @param typeMap
 383             set the XNameAccess object associated with this Connection object.
 384         @throws SQLException
 385             if a database access error occurs.
 386      */
 387     void setTypeMap([in]com::sun::star::container::XNameAccess typeMap)
 388         raises (SQLException);
 389 };
 390
 391
 392 }; }; }; };
 393
 394 /*===========================================================================
 395 ===========================================================================*/
 396
 397 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */