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