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