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