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