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 */ 71published 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 439