1 /*
2 * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.sql;
27
28 import java.util.Properties;
29 import java.util.concurrent.Executor;
30
31 /**
32 * <P>A connection (session) with a specific
33 * database. SQL statements are executed and results are returned
34 * within the context of a connection.
35 * <P>
36 * A <code>Connection</code> object's database is able to provide information
37 * describing its tables, its supported SQL grammar, its stored
38 * procedures, the capabilities of this connection, and so on. This
39 * information is obtained with the <code>getMetaData</code> method.
40 *
41 * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications
42 * should use the appropriate <code>Connection</code> method such as
43 * <code>setAutoCommit</code> or <code>setTransactionIsolation</code>.
44 * Applications should not invoke SQL commands directly to change the connection's
45 * configuration when there is a JDBC method available. By default a <code>Connection</code> object is in
46 * auto-commit mode, which means that it automatically commits changes
47 * after executing each statement. If auto-commit mode has been
48 * disabled, the method <code>commit</code> must be called explicitly in
49 * order to commit changes; otherwise, database changes will not be saved.
50 * <P>
51 * A new <code>Connection</code> object created using the JDBC 2.1 core API
52 * has an initially empty type map associated with it. A user may enter a
53 * custom mapping for a UDT in this type map.
54 * When a UDT is retrieved from a data source with the
55 * method <code>ResultSet.getObject</code>, the <code>getObject</code> method
56 * will check the connection's type map to see if there is an entry for that
57 * UDT. If so, the <code>getObject</code> method will map the UDT to the
58 * class indicated. If there is no entry, the UDT will be mapped using the
59 * standard mapping.
60 * <p>
61 * A user may create a new type map, which is a <code>java.util.Map</code>
62 * object, make an entry in it, and pass it to the <code>java.sql</code>
63 * methods that can perform custom mapping. In this case, the method
64 * will use the given type map instead of the one associated with
65 * the connection.
66 * <p>
67 * For example, the following code fragment specifies that the SQL
68 * type <code>ATHLETES</code> will be mapped to the class
69 * <code>Athletes</code> in the Java programming language.
70 * The code fragment retrieves the type map for the <code>Connection
71 * </code> object <code>con</code>, inserts the entry into it, and then sets
72 * the type map with the new entry as the connection's type map.
73 * <pre>
74 * java.util.Map map = con.getTypeMap();
75 * map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
76 * con.setTypeMap(map);
77 * </pre>
78 *
79 * @see DriverManager#getConnection
80 * @see Statement
81 * @see ResultSet
82 * @see DatabaseMetaData
83 */
84 public interface Connection extends Wrapper, AutoCloseable {
85
86 /**
87 * Creates a <code>Statement</code> object for sending
88 * SQL statements to the database.
89 * SQL statements without parameters are normally
90 * executed using <code>Statement</code> objects. If the same SQL statement
91 * is executed many times, it may be more efficient to use a
92 * <code>PreparedStatement</code> object.
93 * <P>
94 * Result sets created using the returned <code>Statement</code>
95 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
96 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
97 * The holdability of the created result sets can be determined by
98 * calling {@link #getHoldability}.
99 *
100 * @return a new default <code>Statement</code> object
101 * @exception SQLException if a database access error occurs
102 * or this method is called on a closed connection
103 */
104 Statement createStatement() throws SQLException;
105
106 /**
107 * Creates a <code>PreparedStatement</code> object for sending
108 * parameterized SQL statements to the database.
109 * <P>
110 * A SQL statement with or without IN parameters can be
111 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
112 * object can then be used to efficiently execute this statement
113 * multiple times.
114 *
115 * <P><B>Note:</B> This method is optimized for handling
116 * parametric SQL statements that benefit from precompilation. If
117 * the driver supports precompilation,
118 * the method <code>prepareStatement</code> will send
119 * the statement to the database for precompilation. Some drivers
120 * may not support precompilation. In this case, the statement may
121 * not be sent to the database until the <code>PreparedStatement</code>
122 * object is executed. This has no direct effect on users; however, it does
123 * affect which methods throw certain <code>SQLException</code> objects.
124 * <P>
125 * Result sets created using the returned <code>PreparedStatement</code>
126 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
127 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
128 * The holdability of the created result sets can be determined by
129 * calling {@link #getHoldability}.
130 *
131 * @param sql an SQL statement that may contain one or more '?' IN
132 * parameter placeholders
133 * @return a new default <code>PreparedStatement</code> object containing the
134 * pre-compiled SQL statement
135 * @exception SQLException if a database access error occurs
136 * or this method is called on a closed connection
137 */
138 PreparedStatement prepareStatement(String sql)
139 throws SQLException;
140
141 /**
142 * Creates a <code>CallableStatement</code> object for calling
143 * database stored procedures.
144 * The <code>CallableStatement</code> object provides
145 * methods for setting up its IN and OUT parameters, and
146 * methods for executing the call to a stored procedure.
147 *
148 * <P><B>Note:</B> This method is optimized for handling stored
149 * procedure call statements. Some drivers may send the call
150 * statement to the database when the method <code>prepareCall</code>
151 * is done; others
152 * may wait until the <code>CallableStatement</code> object
153 * is executed. This has no
154 * direct effect on users; however, it does affect which method
155 * throws certain SQLExceptions.
156 * <P>
157 * Result sets created using the returned <code>CallableStatement</code>
158 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
159 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
160 * The holdability of the created result sets can be determined by
161 * calling {@link #getHoldability}.
162 *
163 * @param sql an SQL statement that may contain one or more '?'
164 * parameter placeholders. Typically this statement is specified using JDBC
165 * call escape syntax.
166 * @return a new default <code>CallableStatement</code> object containing the
167 * pre-compiled SQL statement
168 * @exception SQLException if a database access error occurs
169 * or this method is called on a closed connection
170 */
171 CallableStatement prepareCall(String sql) throws SQLException;
172
173 /**
174 * Converts the given SQL statement into the system's native SQL grammar.
175 * A driver may convert the JDBC SQL grammar into its system's
176 * native SQL grammar prior to sending it. This method returns the
177 * native form of the statement that the driver would have sent.
178 *
179 * @param sql an SQL statement that may contain one or more '?'
180 * parameter placeholders
181 * @return the native form of this statement
182 * @exception SQLException if a database access error occurs
183 * or this method is called on a closed connection
184 */
185 String nativeSQL(String sql) throws SQLException;
186
187 /**
188 * Sets this connection's auto-commit mode to the given state.
189 * If a connection is in auto-commit mode, then all its SQL
190 * statements will be executed and committed as individual
191 * transactions. Otherwise, its SQL statements are grouped into
192 * transactions that are terminated by a call to either
193 * the method <code>commit</code> or the method <code>rollback</code>.
194 * By default, new connections are in auto-commit
195 * mode.
196 * <P>
197 * The commit occurs when the statement completes. The time when the statement
198 * completes depends on the type of SQL Statement:
199 * <ul>
200 * <li>For DML statements, such as Insert, Update or Delete, and DDL statements,
201 * the statement is complete as soon as it has finished executing.
202 * <li>For Select statements, the statement is complete when the associated result
203 * set is closed.
204 * <li>For <code>CallableStatement</code> objects or for statements that return
205 * multiple results, the statement is complete
206 * when all of the associated result sets have been closed, and all update
207 * counts and output parameters have been retrieved.
208 *</ul>
209 * <P>
210 * <B>NOTE:</B> If this method is called during a transaction and the
211 * auto-commit mode is changed, the transaction is committed. If
212 * <code>setAutoCommit</code> is called and the auto-commit mode is
213 * not changed, the call is a no-op.
214 *
215 * @param autoCommit <code>true</code> to enable auto-commit mode;
216 * <code>false</code> to disable it
217 * @exception SQLException if a database access error occurs,
218 * setAutoCommit(true) is called while participating in a distributed transaction,
219 * or this method is called on a closed connection
220 * @see #getAutoCommit
221 */
222 void setAutoCommit(boolean autoCommit) throws SQLException;
223
224 /**
225 * Retrieves the current auto-commit mode for this <code>Connection</code>
226 * object.
227 *
228 * @return the current state of this <code>Connection</code> object's
229 * auto-commit mode
230 * @exception SQLException if a database access error occurs
231 * or this method is called on a closed connection
232 * @see #setAutoCommit
233 */
234 boolean getAutoCommit() throws SQLException;
235
236 /**
237 * Makes all changes made since the previous
238 * commit/rollback permanent and releases any database locks
239 * currently held by this <code>Connection</code> object.
240 * This method should be
241 * used only when auto-commit mode has been disabled.
242 *
243 * @exception SQLException if a database access error occurs,
244 * this method is called while participating in a distributed transaction,
245 * if this method is called on a closed connection or this
246 * <code>Connection</code> object is in auto-commit mode
247 * @see #setAutoCommit
248 */
249 void commit() throws SQLException;
250
251 /**
252 * Undoes all changes made in the current transaction
253 * and releases any database locks currently held
254 * by this <code>Connection</code> object. This method should be
255 * used only when auto-commit mode has been disabled.
256 *
257 * @exception SQLException if a database access error occurs,
258 * this method is called while participating in a distributed transaction,
259 * this method is called on a closed connection or this
260 * <code>Connection</code> object is in auto-commit mode
261 * @see #setAutoCommit
262 */
263 void rollback() throws SQLException;
264
265 /**
266 * Releases this <code>Connection</code> object's database and JDBC resources
267 * immediately instead of waiting for them to be automatically released.
268 * <P>
269 * Calling the method <code>close</code> on a <code>Connection</code>
270 * object that is already closed is a no-op.
271 * <P>
272 * It is <b>strongly recommended</b> that an application explicitly
273 * commits or rolls back an active transaction prior to calling the
274 * <code>close</code> method. If the <code>close</code> method is called
275 * and there is an active transaction, the results are implementation-defined.
276 *
277 * @exception SQLException if a database access error occurs
278 */
279 void close() throws SQLException;
280
281 /**
282 * Retrieves whether this <code>Connection</code> object has been
283 * closed. A connection is closed if the method <code>close</code>
284 * has been called on it or if certain fatal errors have occurred.
285 * This method is guaranteed to return <code>true</code> only when
286 * it is called after the method <code>Connection.close</code> has
287 * been called.
288 * <P>
289 * This method generally cannot be called to determine whether a
290 * connection to a database is valid or invalid. A typical client
291 * can determine that a connection is invalid by catching any
292 * exceptions that might be thrown when an operation is attempted.
293 *
294 * @return <code>true</code> if this <code>Connection</code> object
295 * is closed; <code>false</code> if it is still open
296 * @exception SQLException if a database access error occurs
297 */
298 boolean isClosed() throws SQLException;
299
300 //======================================================================
301 // Advanced features:
302
303 /**
304 * Retrieves a <code>DatabaseMetaData</code> object that contains
305 * metadata about the database to which this
306 * <code>Connection</code> object represents a connection.
307 * The metadata includes information about the database's
308 * tables, its supported SQL grammar, its stored
309 * procedures, the capabilities of this connection, and so on.
310 *
311 * @return a <code>DatabaseMetaData</code> object for this
312 * <code>Connection</code> object
313 * @exception SQLException if a database access error occurs
314 * or this method is called on a closed connection
315 */
316 DatabaseMetaData getMetaData() throws SQLException;
317
318 /**
319 * Puts this connection in read-only mode as a hint to the driver to enable
320 * database optimizations.
321 *
322 * <P><B>Note:</B> This method cannot be called during a transaction.
323 *
324 * @param readOnly <code>true</code> enables read-only mode;
325 * <code>false</code> disables it
326 * @exception SQLException if a database access error occurs, this
327 * method is called on a closed connection or this
328 * method is called during a transaction
329 */
330 void setReadOnly(boolean readOnly) throws SQLException;
331
332 /**
333 * Retrieves whether this <code>Connection</code>
334 * object is in read-only mode.
335 *
336 * @return <code>true</code> if this <code>Connection</code> object
337 * is read-only; <code>false</code> otherwise
338 * @exception SQLException if a database access error occurs
339 * or this method is called on a closed connection
340 */
341 boolean isReadOnly() throws SQLException;
342
343 /**
344 * Sets the given catalog name in order to select
345 * a subspace of this <code>Connection</code> object's database
346 * in which to work.
347 * <P>
348 * If the driver does not support catalogs, it will
349 * silently ignore this request.
350 * <p>
351 * Calling {@code setCatalog} has no effect on previously created or prepared
352 * {@code Statement} objects. It is implementation defined whether a DBMS
353 * prepare operation takes place immediately when the {@code Connection}
354 * method {@code prepareStatement} or {@code prepareCall} is invoked.
355 * For maximum portability, {@code setCatalog} should be called before a
356 * {@code Statement} is created or prepared.
357 *
358 * @param catalog the name of a catalog (subspace in this
359 * <code>Connection</code> object's database) in which to work
360 * @exception SQLException if a database access error occurs
361 * or this method is called on a closed connection
362 * @see #getCatalog
363 */
364 void setCatalog(String catalog) throws SQLException;
365
366 /**
367 * Retrieves this <code>Connection</code> object's current catalog name.
368 *
369 * @return the current catalog name or <code>null</code> if there is none
370 * @exception SQLException if a database access error occurs
371 * or this method is called on a closed connection
372 * @see #setCatalog
373 */
374 String getCatalog() throws SQLException;
375
376 /**
377 * A constant indicating that transactions are not supported.
378 */
379 int TRANSACTION_NONE = 0;
380
381 /**
382 * A constant indicating that
383 * dirty reads, non-repeatable reads and phantom reads can occur.
384 * This level allows a row changed by one transaction to be read
385 * by another transaction before any changes in that row have been
386 * committed (a "dirty read"). If any of the changes are rolled back,
387 * the second transaction will have retrieved an invalid row.
388 */
389 int TRANSACTION_READ_UNCOMMITTED = 1;
390
391 /**
392 * A constant indicating that
393 * dirty reads are prevented; non-repeatable reads and phantom
394 * reads can occur. This level only prohibits a transaction
395 * from reading a row with uncommitted changes in it.
396 */
397 int TRANSACTION_READ_COMMITTED = 2;
398
399 /**
400 * A constant indicating that
401 * dirty reads and non-repeatable reads are prevented; phantom
402 * reads can occur. This level prohibits a transaction from
403 * reading a row with uncommitted changes in it, and it also
404 * prohibits the situation where one transaction reads a row,
405 * a second transaction alters the row, and the first transaction
406 * rereads the row, getting different values the second time
407 * (a "non-repeatable read").
408 */
409 int TRANSACTION_REPEATABLE_READ = 4;
410
411 /**
412 * A constant indicating that
413 * dirty reads, non-repeatable reads and phantom reads are prevented.
414 * This level includes the prohibitions in
415 * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the
416 * situation where one transaction reads all rows that satisfy
417 * a <code>WHERE</code> condition, a second transaction inserts a row that
418 * satisfies that <code>WHERE</code> condition, and the first transaction
419 * rereads for the same condition, retrieving the additional
420 * "phantom" row in the second read.
421 */
422 int TRANSACTION_SERIALIZABLE = 8;
423
424 /**
425 * Attempts to change the transaction isolation level for this
426 * <code>Connection</code> object to the one given.
427 * The constants defined in the interface <code>Connection</code>
428 * are the possible transaction isolation levels.
429 * <P>
430 * <B>Note:</B> If this method is called during a transaction, the result
431 * is implementation-defined.
432 *
433 * @param level one of the following <code>Connection</code> constants:
434 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
435 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
436 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
437 * <code>Connection.TRANSACTION_SERIALIZABLE</code>.
438 * (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used
439 * because it specifies that transactions are not supported.)
440 * @exception SQLException if a database access error occurs, this
441 * method is called on a closed connection
442 * or the given parameter is not one of the <code>Connection</code>
443 * constants
444 * @see DatabaseMetaData#supportsTransactionIsolationLevel
445 * @see #getTransactionIsolation
446 */
447 void setTransactionIsolation(int level) throws SQLException;
448
449 /**
450 * Retrieves this <code>Connection</code> object's current
451 * transaction isolation level.
452 *
453 * @return the current transaction isolation level, which will be one
454 * of the following constants:
455 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
456 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
457 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>,
458 * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
459 * <code>Connection.TRANSACTION_NONE</code>.
460 * @exception SQLException if a database access error occurs
461 * or this method is called on a closed connection
462 * @see #setTransactionIsolation
463 */
464 int getTransactionIsolation() throws SQLException;
465
466 /**
467 * Retrieves the first warning reported by calls on this
468 * <code>Connection</code> object. If there is more than one
469 * warning, subsequent warnings will be chained to the first one
470 * and can be retrieved by calling the method
471 * <code>SQLWarning.getNextWarning</code> on the warning
472 * that was retrieved previously.
473 * <P>
474 * This method may not be
475 * called on a closed connection; doing so will cause an
476 * <code>SQLException</code> to be thrown.
477 *
478 * <P><B>Note:</B> Subsequent warnings will be chained to this
479 * SQLWarning.
480 *
481 * @return the first <code>SQLWarning</code> object or <code>null</code>
482 * if there are none
483 * @exception SQLException if a database access error occurs or
484 * this method is called on a closed connection
485 * @see SQLWarning
486 */
487 SQLWarning getWarnings() throws SQLException;
488
489 /**
490 * Clears all warnings reported for this <code>Connection</code> object.
491 * After a call to this method, the method <code>getWarnings</code>
492 * returns <code>null</code> until a new warning is
493 * reported for this <code>Connection</code> object.
494 *
495 * @exception SQLException if a database access error occurs
496 * or this method is called on a closed connection
497 */
498 void clearWarnings() throws SQLException;
499
500
501 //--------------------------JDBC 2.0-----------------------------
502
503 /**
504 * Creates a <code>Statement</code> object that will generate
505 * <code>ResultSet</code> objects with the given type and concurrency.
506 * This method is the same as the <code>createStatement</code> method
507 * above, but it allows the default result set
508 * type and concurrency to be overridden.
509 * The holdability of the created result sets can be determined by
510 * calling {@link #getHoldability}.
511 *
512 * @param resultSetType a result set type; one of
513 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
514 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
515 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
516 * @param resultSetConcurrency a concurrency type; one of
517 * <code>ResultSet.CONCUR_READ_ONLY</code> or
518 * <code>ResultSet.CONCUR_UPDATABLE</code>
519 * @return a new <code>Statement</code> object that will generate
520 * <code>ResultSet</code> objects with the given type and
521 * concurrency
522 * @exception SQLException if a database access error occurs, this
523 * method is called on a closed connection
524 * or the given parameters are not <code>ResultSet</code>
525 * constants indicating type and concurrency
526 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
527 * this method or this method is not supported for the specified result
528 * set type and result set concurrency.
529 * @since 1.2
530 */
531 Statement createStatement(int resultSetType, int resultSetConcurrency)
532 throws SQLException;
533
534 /**
535 *
536 * Creates a <code>PreparedStatement</code> object that will generate
537 * <code>ResultSet</code> objects with the given type and concurrency.
538 * This method is the same as the <code>prepareStatement</code> method
539 * above, but it allows the default result set
540 * type and concurrency to be overridden.
541 * The holdability of the created result sets can be determined by
542 * calling {@link #getHoldability}.
543 *
544 * @param sql a <code>String</code> object that is the SQL statement to
545 * be sent to the database; may contain one or more '?' IN
546 * parameters
547 * @param resultSetType a result set type; one of
548 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
549 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
550 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
551 * @param resultSetConcurrency a concurrency type; one of
552 * <code>ResultSet.CONCUR_READ_ONLY</code> or
553 * <code>ResultSet.CONCUR_UPDATABLE</code>
554 * @return a new PreparedStatement object containing the
555 * pre-compiled SQL statement that will produce <code>ResultSet</code>
556 * objects with the given type and concurrency
557 * @exception SQLException if a database access error occurs, this
558 * method is called on a closed connection
559 * or the given parameters are not <code>ResultSet</code>
560 * constants indicating type and concurrency
561 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
562 * this method or this method is not supported for the specified result
563 * set type and result set concurrency.
564 * @since 1.2
565 */
566 PreparedStatement prepareStatement(String sql, int resultSetType,
567 int resultSetConcurrency)
568 throws SQLException;
569
570 /**
571 * Creates a <code>CallableStatement</code> object that will generate
572 * <code>ResultSet</code> objects with the given type and concurrency.
573 * This method is the same as the <code>prepareCall</code> method
574 * above, but it allows the default result set
575 * type and concurrency to be overridden.
576 * The holdability of the created result sets can be determined by
577 * calling {@link #getHoldability}.
578 *
579 * @param sql a <code>String</code> object that is the SQL statement to
580 * be sent to the database; may contain on or more '?' parameters
581 * @param resultSetType a result set type; one of
582 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
583 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
584 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
585 * @param resultSetConcurrency a concurrency type; one of
586 * <code>ResultSet.CONCUR_READ_ONLY</code> or
587 * <code>ResultSet.CONCUR_UPDATABLE</code>
588 * @return a new <code>CallableStatement</code> object containing the
589 * pre-compiled SQL statement that will produce <code>ResultSet</code>
590 * objects with the given type and concurrency
591 * @exception SQLException if a database access error occurs, this method
592 * is called on a closed connection
593 * or the given parameters are not <code>ResultSet</code>
594 * constants indicating type and concurrency
595 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
596 * this method or this method is not supported for the specified result
597 * set type and result set concurrency.
598 * @since 1.2
599 */
600 CallableStatement prepareCall(String sql, int resultSetType,
601 int resultSetConcurrency) throws SQLException;
602
603 /**
604 * Retrieves the <code>Map</code> object associated with this
605 * <code>Connection</code> object.
606 * Unless the application has added an entry, the type map returned
607 * will be empty.
608 * <p>
609 * You must invoke <code>setTypeMap</code> after making changes to the
610 * <code>Map</code> object returned from
611 * <code>getTypeMap</code> as a JDBC driver may create an internal
612 * copy of the <code>Map</code> object passed to <code>setTypeMap</code>:
613 *
614 * <pre>
615 * Map<String,Class<?>> myMap = con.getTypeMap();
616 * myMap.put("mySchemaName.ATHLETES", Athletes.class);
617 * con.setTypeMap(myMap);
618 * </pre>
619 * @return the <code>java.util.Map</code> object associated
620 * with this <code>Connection</code> object
621 * @exception SQLException if a database access error occurs
622 * or this method is called on a closed connection
623 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
624 * this method
625 * @since 1.2
626 * @see #setTypeMap
627 */
628 java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
629
630 /**
631 * Installs the given <code>TypeMap</code> object as the type map for
632 * this <code>Connection</code> object. The type map will be used for the
633 * custom mapping of SQL structured types and distinct types.
634 * <p>
635 * You must set the values for the <code>TypeMap</code> prior to
636 * callng <code>setMap</code> as a JDBC driver may create an internal copy
637 * of the <code>TypeMap</code>:
638 *
639 * <pre>
640 * Map myMap<String,Class<?>> = new HashMap<String,Class<?>>();
641 * myMap.put("mySchemaName.ATHLETES", Athletes.class);
642 * con.setTypeMap(myMap);
643 * </pre>
644 * @param map the <code>java.util.Map</code> object to install
645 * as the replacement for this <code>Connection</code>
646 * object's default type map
647 * @exception SQLException if a database access error occurs, this
648 * method is called on a closed connection or
649 * the given parameter is not a <code>java.util.Map</code>
650 * object
651 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
652 * this method
653 * @since 1.2
654 * @see #getTypeMap
655 */
656 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
657
658 //--------------------------JDBC 3.0-----------------------------
659
660
661 /**
662 * Changes the default holdability of <code>ResultSet</code> objects
663 * created using this <code>Connection</code> object to the given
664 * holdability. The default holdability of <code>ResultSet</code> objects
665 * can be determined by invoking
666 * {@link DatabaseMetaData#getResultSetHoldability}.
667 *
668 * @param holdability a <code>ResultSet</code> holdability constant; one of
669 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
670 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
671 * @throws SQLException if a database access occurs, this method is called
672 * on a closed connection, or the given parameter
673 * is not a <code>ResultSet</code> constant indicating holdability
674 * @exception SQLFeatureNotSupportedException if the given holdability is not supported
675 * @see #getHoldability
676 * @see DatabaseMetaData#getResultSetHoldability
677 * @see ResultSet
678 * @since 1.4
679 */
680 void setHoldability(int holdability) throws SQLException;
681
682 /**
683 * Retrieves the current holdability of <code>ResultSet</code> objects
684 * created using this <code>Connection</code> object.
685 *
686 * @return the holdability, one of
687 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
688 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
689 * @throws SQLException if a database access error occurs
690 * or this method is called on a closed connection
691 * @see #setHoldability
692 * @see DatabaseMetaData#getResultSetHoldability
693 * @see ResultSet
694 * @since 1.4
695 */
696 int getHoldability() throws SQLException;
697
698 /**
699 * Creates an unnamed savepoint in the current transaction and
700 * returns the new <code>Savepoint</code> object that represents it.
701 *
702 *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
703 *savepoint.
704 *
705 * @return the new <code>Savepoint</code> object
706 * @exception SQLException if a database access error occurs,
707 * this method is called while participating in a distributed transaction,
708 * this method is called on a closed connection
709 * or this <code>Connection</code> object is currently in
710 * auto-commit mode
711 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
712 * this method
713 * @see Savepoint
714 * @since 1.4
715 */
716 Savepoint setSavepoint() throws SQLException;
717
718 /**
719 * Creates a savepoint with the given name in the current transaction
720 * and returns the new <code>Savepoint</code> object that represents it.
721 *
722 * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
723 *savepoint.
724 *
725 * @param name a <code>String</code> containing the name of the savepoint
726 * @return the new <code>Savepoint</code> object
727 * @exception SQLException if a database access error occurs,
728 * this method is called while participating in a distributed transaction,
729 * this method is called on a closed connection
730 * or this <code>Connection</code> object is currently in
731 * auto-commit mode
732 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
733 * this method
734 * @see Savepoint
735 * @since 1.4
736 */
737 Savepoint setSavepoint(String name) throws SQLException;
738
739 /**
740 * Undoes all changes made after the given <code>Savepoint</code> object
741 * was set.
742 * <P>
743 * This method should be used only when auto-commit has been disabled.
744 *
745 * @param savepoint the <code>Savepoint</code> object to roll back to
746 * @exception SQLException if a database access error occurs,
747 * this method is called while participating in a distributed transaction,
748 * this method is called on a closed connection,
749 * the <code>Savepoint</code> object is no longer valid,
750 * or this <code>Connection</code> object is currently in
751 * auto-commit mode
752 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
753 * this method
754 * @see Savepoint
755 * @see #rollback
756 * @since 1.4
757 */
758 void rollback(Savepoint savepoint) throws SQLException;
759
760 /**
761 * Removes the specified <code>Savepoint</code> and subsequent <code>Savepoint</code> objects from the current
762 * transaction. Any reference to the savepoint after it have been removed
763 * will cause an <code>SQLException</code> to be thrown.
764 *
765 * @param savepoint the <code>Savepoint</code> object to be removed
766 * @exception SQLException if a database access error occurs, this
767 * method is called on a closed connection or
768 * the given <code>Savepoint</code> object is not a valid
769 * savepoint in the current transaction
770 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
771 * this method
772 * @since 1.4
773 */
774 void releaseSavepoint(Savepoint savepoint) throws SQLException;
775
776 /**
777 * Creates a <code>Statement</code> object that will generate
778 * <code>ResultSet</code> objects with the given type, concurrency,
779 * and holdability.
780 * This method is the same as the <code>createStatement</code> method
781 * above, but it allows the default result set
782 * type, concurrency, and holdability to be overridden.
783 *
784 * @param resultSetType one of the following <code>ResultSet</code>
785 * constants:
786 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
787 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
788 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
789 * @param resultSetConcurrency one of the following <code>ResultSet</code>
790 * constants:
791 * <code>ResultSet.CONCUR_READ_ONLY</code> or
792 * <code>ResultSet.CONCUR_UPDATABLE</code>
793 * @param resultSetHoldability one of the following <code>ResultSet</code>
794 * constants:
795 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
796 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
797 * @return a new <code>Statement</code> object that will generate
798 * <code>ResultSet</code> objects with the given type,
799 * concurrency, and holdability
800 * @exception SQLException if a database access error occurs, this
801 * method is called on a closed connection
802 * or the given parameters are not <code>ResultSet</code>
803 * constants indicating type, concurrency, and holdability
804 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
805 * this method or this method is not supported for the specified result
806 * set type, result set holdability and result set concurrency.
807 * @see ResultSet
808 * @since 1.4
809 */
810 Statement createStatement(int resultSetType, int resultSetConcurrency,
811 int resultSetHoldability) throws SQLException;
812
813 /**
814 * Creates a <code>PreparedStatement</code> object that will generate
815 * <code>ResultSet</code> objects with the given type, concurrency,
816 * and holdability.
817 * <P>
818 * This method is the same as the <code>prepareStatement</code> method
819 * above, but it allows the default result set
820 * type, concurrency, and holdability to be overridden.
821 *
822 * @param sql a <code>String</code> object that is the SQL statement to
823 * be sent to the database; may contain one or more '?' IN
824 * parameters
825 * @param resultSetType one of the following <code>ResultSet</code>
826 * constants:
827 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
828 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
829 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
830 * @param resultSetConcurrency one of the following <code>ResultSet</code>
831 * constants:
832 * <code>ResultSet.CONCUR_READ_ONLY</code> or
833 * <code>ResultSet.CONCUR_UPDATABLE</code>
834 * @param resultSetHoldability one of the following <code>ResultSet</code>
835 * constants:
836 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
837 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
838 * @return a new <code>PreparedStatement</code> object, containing the
839 * pre-compiled SQL statement, that will generate
840 * <code>ResultSet</code> objects with the given type,
841 * concurrency, and holdability
842 * @exception SQLException if a database access error occurs, this
843 * method is called on a closed connection
844 * or the given parameters are not <code>ResultSet</code>
845 * constants indicating type, concurrency, and holdability
846 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
847 * this method or this method is not supported for the specified result
848 * set type, result set holdability and result set concurrency.
849 * @see ResultSet
850 * @since 1.4
851 */
852 PreparedStatement prepareStatement(String sql, int resultSetType,
853 int resultSetConcurrency, int resultSetHoldability)
854 throws SQLException;
855
856 /**
857 * Creates a <code>CallableStatement</code> object that will generate
858 * <code>ResultSet</code> objects with the given type and concurrency.
859 * This method is the same as the <code>prepareCall</code> method
860 * above, but it allows the default result set
861 * type, result set concurrency type and holdability to be overridden.
862 *
863 * @param sql a <code>String</code> object that is the SQL statement to
864 * be sent to the database; may contain on or more '?' parameters
865 * @param resultSetType one of the following <code>ResultSet</code>
866 * constants:
867 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
868 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
869 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
870 * @param resultSetConcurrency one of the following <code>ResultSet</code>
871 * constants:
872 * <code>ResultSet.CONCUR_READ_ONLY</code> or
873 * <code>ResultSet.CONCUR_UPDATABLE</code>
874 * @param resultSetHoldability one of the following <code>ResultSet</code>
875 * constants:
876 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
877 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
878 * @return a new <code>CallableStatement</code> object, containing the
879 * pre-compiled SQL statement, that will generate
880 * <code>ResultSet</code> objects with the given type,
881 * concurrency, and holdability
882 * @exception SQLException if a database access error occurs, this
883 * method is called on a closed connection
884 * or the given parameters are not <code>ResultSet</code>
885 * constants indicating type, concurrency, and holdability
886 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
887 * this method or this method is not supported for the specified result
888 * set type, result set holdability and result set concurrency.
889 * @see ResultSet
890 * @since 1.4
891 */
892 CallableStatement prepareCall(String sql, int resultSetType,
893 int resultSetConcurrency,
894 int resultSetHoldability) throws SQLException;
895
896
897 /**
898 * Creates a default <code>PreparedStatement</code> object that has
899 * the capability to retrieve auto-generated keys. The given constant
900 * tells the driver whether it should make auto-generated keys
901 * available for retrieval. This parameter is ignored if the SQL statement
902 * is not an <code>INSERT</code> statement, or an SQL statement able to return
903 * auto-generated keys (the list of such statements is vendor-specific).
904 * <P>
905 * <B>Note:</B> This method is optimized for handling
906 * parametric SQL statements that benefit from precompilation. If
907 * the driver supports precompilation,
908 * the method <code>prepareStatement</code> will send
909 * the statement to the database for precompilation. Some drivers
910 * may not support precompilation. In this case, the statement may
911 * not be sent to the database until the <code>PreparedStatement</code>
912 * object is executed. This has no direct effect on users; however, it does
913 * affect which methods throw certain SQLExceptions.
914 * <P>
915 * Result sets created using the returned <code>PreparedStatement</code>
916 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
917 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
918 * The holdability of the created result sets can be determined by
919 * calling {@link #getHoldability}.
920 *
921 * @param sql an SQL statement that may contain one or more '?' IN
922 * parameter placeholders
923 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
924 * should be returned; one of
925 * <code>Statement.RETURN_GENERATED_KEYS</code> or
926 * <code>Statement.NO_GENERATED_KEYS</code>
927 * @return a new <code>PreparedStatement</code> object, containing the
928 * pre-compiled SQL statement, that will have the capability of
929 * returning auto-generated keys
930 * @exception SQLException if a database access error occurs, this
931 * method is called on a closed connection
932 * or the given parameter is not a <code>Statement</code>
933 * constant indicating whether auto-generated keys should be
934 * returned
935 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
936 * this method with a constant of Statement.RETURN_GENERATED_KEYS
937 * @since 1.4
938 */
939 PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
940 throws SQLException;
941
942 /**
943 * Creates a default <code>PreparedStatement</code> object capable
944 * of returning the auto-generated keys designated by the given array.
945 * This array contains the indexes of the columns in the target
946 * table that contain the auto-generated keys that should be made
947 * available. The driver will ignore the array if the SQL statement
948 * is not an <code>INSERT</code> statement, or an SQL statement able to return
949 * auto-generated keys (the list of such statements is vendor-specific).
950 *<p>
951 * An SQL statement with or without IN parameters can be
952 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
953 * object can then be used to efficiently execute this statement
954 * multiple times.
955 * <P>
956 * <B>Note:</B> This method is optimized for handling
957 * parametric SQL statements that benefit from precompilation. If
958 * the driver supports precompilation,
959 * the method <code>prepareStatement</code> will send
960 * the statement to the database for precompilation. Some drivers
961 * may not support precompilation. In this case, the statement may
962 * not be sent to the database until the <code>PreparedStatement</code>
963 * object is executed. This has no direct effect on users; however, it does
964 * affect which methods throw certain SQLExceptions.
965 * <P>
966 * Result sets created using the returned <code>PreparedStatement</code>
967 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
968 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
969 * The holdability of the created result sets can be determined by
970 * calling {@link #getHoldability}.
971 *
972 * @param sql an SQL statement that may contain one or more '?' IN
973 * parameter placeholders
974 * @param columnIndexes an array of column indexes indicating the columns
975 * that should be returned from the inserted row or rows
976 * @return a new <code>PreparedStatement</code> object, containing the
977 * pre-compiled statement, that is capable of returning the
978 * auto-generated keys designated by the given array of column
979 * indexes
980 * @exception SQLException if a database access error occurs
981 * or this method is called on a closed connection
982 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
983 * this method
984 *
985 * @since 1.4
986 */
987 PreparedStatement prepareStatement(String sql, int columnIndexes[])
988 throws SQLException;
989
990 /**
991 * Creates a default <code>PreparedStatement</code> object capable
992 * of returning the auto-generated keys designated by the given array.
993 * This array contains the names of the columns in the target
994 * table that contain the auto-generated keys that should be returned.
995 * The driver will ignore the array if the SQL statement
996 * is not an <code>INSERT</code> statement, or an SQL statement able to return
997 * auto-generated keys (the list of such statements is vendor-specific).
998 * <P>
999 * An SQL statement with or without IN parameters can be
1000 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
1001 * object can then be used to efficiently execute this statement
1002 * multiple times.
1003 * <P>
1004 * <B>Note:</B> This method is optimized for handling
1005 * parametric SQL statements that benefit from precompilation. If
1006 * the driver supports precompilation,
1007 * the method <code>prepareStatement</code> will send
1008 * the statement to the database for precompilation. Some drivers
1009 * may not support precompilation. In this case, the statement may
1010 * not be sent to the database until the <code>PreparedStatement</code>
1011 * object is executed. This has no direct effect on users; however, it does
1012 * affect which methods throw certain SQLExceptions.
1013 * <P>
1014 * Result sets created using the returned <code>PreparedStatement</code>
1015 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
1016 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
1017 * The holdability of the created result sets can be determined by
1018 * calling {@link #getHoldability}.
1019 *
1020 * @param sql an SQL statement that may contain one or more '?' IN
1021 * parameter placeholders
1022 * @param columnNames an array of column names indicating the columns
1023 * that should be returned from the inserted row or rows
1024 * @return a new <code>PreparedStatement</code> object, containing the
1025 * pre-compiled statement, that is capable of returning the
1026 * auto-generated keys designated by the given array of column
1027 * names
1028 * @exception SQLException if a database access error occurs
1029 * or this method is called on a closed connection
1030 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1031 * this method
1032 *
1033 * @since 1.4
1034 */
1035 PreparedStatement prepareStatement(String sql, String columnNames[])
1036 throws SQLException;
1037
1038 /**
1039 * Constructs an object that implements the <code>Clob</code> interface. The object
1040 * returned initially contains no data. The <code>setAsciiStream</code>,
1041 * <code>setCharacterStream</code> and <code>setString</code> methods of
1042 * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>.
1043 * @return An object that implements the <code>Clob</code> interface
1044 * @throws SQLException if an object that implements the
1045 * <code>Clob</code> interface can not be constructed, this method is
1046 * called on a closed connection or a database access error occurs.
1047 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1048 * this data type
1049 *
1050 * @since 1.6
1051 */
1052 Clob createClob() throws SQLException;
1053
1054 /**
1055 * Constructs an object that implements the <code>Blob</code> interface. The object
1056 * returned initially contains no data. The <code>setBinaryStream</code> and
1057 * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to
1058 * the <code>Blob</code>.
1059 * @return An object that implements the <code>Blob</code> interface
1060 * @throws SQLException if an object that implements the
1061 * <code>Blob</code> interface can not be constructed, this method is
1062 * called on a closed connection or a database access error occurs.
1063 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1064 * this data type
1065 *
1066 * @since 1.6
1067 */
1068 Blob createBlob() throws SQLException;
1069
1070 /**
1071 * Constructs an object that implements the <code>NClob</code> interface. The object
1072 * returned initially contains no data. The <code>setAsciiStream</code>,
1073 * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may
1074 * be used to add data to the <code>NClob</code>.
1075 * @return An object that implements the <code>NClob</code> interface
1076 * @throws SQLException if an object that implements the
1077 * <code>NClob</code> interface can not be constructed, this method is
1078 * called on a closed connection or a database access error occurs.
1079 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1080 * this data type
1081 *
1082 * @since 1.6
1083 */
1084 NClob createNClob() throws SQLException;
1085
1086 /**
1087 * Constructs an object that implements the <code>SQLXML</code> interface. The object
1088 * returned initially contains no data. The <code>createXmlStreamWriter</code> object and
1089 * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code>
1090 * object.
1091 * @return An object that implements the <code>SQLXML</code> interface
1092 * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not
1093 * be constructed, this method is
1094 * called on a closed connection or a database access error occurs.
1095 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1096 * this data type
1097 * @since 1.6
1098 */
1099 SQLXML createSQLXML() throws SQLException;
1100
1101 /**
1102 * Returns true if the connection has not been closed and is still valid.
1103 * The driver shall submit a query on the connection or use some other
1104 * mechanism that positively verifies the connection is still valid when
1105 * this method is called.
1106 * <p>
1107 * The query submitted by the driver to validate the connection shall be
1108 * executed in the context of the current transaction.
1109 *
1110 * @param timeout - The time in seconds to wait for the database operation
1111 * used to validate the connection to complete. If
1112 * the timeout period expires before the operation
1113 * completes, this method returns false. A value of
1114 * 0 indicates a timeout is not applied to the
1115 * database operation.
1116 *
1117 * @return true if the connection is valid, false otherwise
1118 * @exception SQLException if the value supplied for <code>timeout</code>
1119 * is less than 0
1120 * @since 1.6
1121 *
1122 * @see java.sql.DatabaseMetaData#getClientInfoProperties
1123 */
1124 boolean isValid(int timeout) throws SQLException;
1125
1126 /**
1127 * Sets the value of the client info property specified by name to the
1128 * value specified by value.
1129 * <p>
1130 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1131 * method to determine the client info properties supported by the driver
1132 * and the maximum length that may be specified for each property.
1133 * <p>
1134 * The driver stores the value specified in a suitable location in the
1135 * database. For example in a special register, session parameter, or
1136 * system table column. For efficiency the driver may defer setting the
1137 * value in the database until the next time a statement is executed or
1138 * prepared. Other than storing the client information in the appropriate
1139 * place in the database, these methods shall not alter the behavior of
1140 * the connection in anyway. The values supplied to these methods are
1141 * used for accounting, diagnostics and debugging purposes only.
1142 * <p>
1143 * The driver shall generate a warning if the client info name specified
1144 * is not recognized by the driver.
1145 * <p>
1146 * If the value specified to this method is greater than the maximum
1147 * length for the property the driver may either truncate the value and
1148 * generate a warning or generate a <code>SQLClientInfoException</code>. If the driver
1149 * generates a <code>SQLClientInfoException</code>, the value specified was not set on the
1150 * connection.
1151 * <p>
1152 * The following are standard client info properties. Drivers are not
1153 * required to support these properties however if the driver supports a
1154 * client info property that can be described by one of the standard
1155 * properties, the standard property name should be used.
1156 *
1157 * <ul>
1158 * <li>ApplicationName - The name of the application currently utilizing
1159 * the connection</li>
1160 * <li>ClientUser - The name of the user that the application using
1161 * the connection is performing work for. This may
1162 * not be the same as the user name that was used
1163 * in establishing the connection.</li>
1164 * <li>ClientHostname - The hostname of the computer the application
1165 * using the connection is running on.</li>
1166 * </ul>
1167 *
1168 * @param name The name of the client info property to set
1169 * @param value The value to set the client info property to. If the
1170 * value is null, the current value of the specified
1171 * property is cleared.
1172 *
1173 * @throws SQLClientInfoException if the database server returns an error while
1174 * setting the client info value on the database server or this method
1175 * is called on a closed connection
1176 *
1177 * @since 1.6
1178 */
1179 void setClientInfo(String name, String value)
1180 throws SQLClientInfoException;
1181
1182 /**
1183 * Sets the value of the connection's client info properties. The
1184 * <code>Properties</code> object contains the names and values of the client info
1185 * properties to be set. The set of client info properties contained in
1186 * the properties list replaces the current set of client info properties
1187 * on the connection. If a property that is currently set on the
1188 * connection is not present in the properties list, that property is
1189 * cleared. Specifying an empty properties list will clear all of the
1190 * properties on the connection. See <code>setClientInfo (String, String)</code> for
1191 * more information.
1192 * <p>
1193 * If an error occurs in setting any of the client info properties, a
1194 * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code>
1195 * contains information indicating which client info properties were not set.
1196 * The state of the client information is unknown because
1197 * some databases do not allow multiple client info properties to be set
1198 * atomically. For those databases, one or more properties may have been
1199 * set before the error occurred.
1200 *
1201 *
1202 * @param properties the list of client info properties to set
1203 *
1204 * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String)
1205 * @since 1.6
1206 *
1207 * @throws SQLClientInfoException if the database server returns an error while
1208 * setting the clientInfo values on the database server or this method
1209 * is called on a closed connection
1210 *
1211 */
1212 void setClientInfo(Properties properties)
1213 throws SQLClientInfoException;
1214
1215 /**
1216 * Returns the value of the client info property specified by name. This
1217 * method may return null if the specified client info property has not
1218 * been set and does not have a default value. This method will also
1219 * return null if the specified client info property name is not supported
1220 * by the driver.
1221 * <p>
1222 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1223 * method to determine the client info properties supported by the driver.
1224 *
1225 * @param name The name of the client info property to retrieve
1226 *
1227 * @return The value of the client info property specified
1228 *
1229 * @throws SQLException if the database server returns an error when
1230 * fetching the client info value from the database
1231 * or this method is called on a closed connection
1232 *
1233 * @since 1.6
1234 *
1235 * @see java.sql.DatabaseMetaData#getClientInfoProperties
1236 */
1237 String getClientInfo(String name)
1238 throws SQLException;
1239
1240 /**
1241 * Returns a list containing the name and current value of each client info
1242 * property supported by the driver. The value of a client info property
1243 * may be null if the property has not been set and does not have a
1244 * default value.
1245 *
1246 * @return A <code>Properties</code> object that contains the name and current value of
1247 * each of the client info properties supported by the driver.
1248 *
1249 * @throws SQLException if the database server returns an error when
1250 * fetching the client info values from the database
1251 * or this method is called on a closed connection
1252 *
1253 * @since 1.6
1254 */
1255 Properties getClientInfo()
1256 throws SQLException;
1257
1258 /**
1259 * Factory method for creating Array objects.
1260 *<p>
1261 * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object
1262 * that maps to a primitive data type, then it is implementation-defined
1263 * whether the <code>Array</code> object is an array of that primitive
1264 * data type or an array of <code>Object</code>.
1265 * <p>
1266 * <b>Note: </b>The JDBC driver is responsible for mapping the elements
1267 * <code>Object</code> array to the default JDBC SQL type defined in
1268 * java.sql.Types for the given class of <code>Object</code>. The default
1269 * mapping is specified in Appendix B of the JDBC specification. If the
1270 * resulting JDBC type is not the appropriate type for the given typeName then
1271 * it is implementation defined whether an <code>SQLException</code> is
1272 * thrown or the driver supports the resulting conversion.
1273 *
1274 * @param typeName the SQL name of the type the elements of the array map to. The typeName is a
1275 * database-specific name which may be the name of a built-in type, a user-defined type or a standard SQL type supported by this database. This
1276 * is the value returned by <code>Array.getBaseTypeName</code>
1277 * @param elements the elements that populate the returned object
1278 * @return an Array object whose elements map to the specified SQL type
1279 * @throws SQLException if a database error occurs, the JDBC type is not
1280 * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection
1281 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type
1282 * @since 1.6
1283 */
1284 Array createArrayOf(String typeName, Object[] elements) throws
1285 SQLException;
1286
1287 /**
1288 * Factory method for creating Struct objects.
1289 *
1290 * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code>
1291 * object maps to. The typeName is the name of a user-defined type that
1292 * has been defined for this database. It is the value returned by
1293 * <code>Struct.getSQLTypeName</code>.
1294
1295 * @param attributes the attributes that populate the returned object
1296 * @return a Struct object that maps to the given SQL type and is populated with the given attributes
1297 * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection
1298 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type
1299 * @since 1.6
1300 */
1301 Struct createStruct(String typeName, Object[] attributes)
1302 throws SQLException;
1303
1304 //--------------------------JDBC 4.1 -----------------------------
1305
1306 /**
1307 * Sets the given schema name to access.
1308 * <P>
1309 * If the driver does not support schemas, it will
1310 * silently ignore this request.
1311 * <p>
1312 * Calling {@code setSchema} has no effect on previously created or prepared
1313 * {@code Statement} objects. It is implementation defined whether a DBMS
1314 * prepare operation takes place immediately when the {@code Connection}
1315 * method {@code prepareStatement} or {@code prepareCall} is invoked.
1316 * For maximum portability, {@code setSchema} should be called before a
1317 * {@code Statement} is created or prepared.
1318 *
1319 * @param schema the name of a schema in which to work
1320 * @exception SQLException if a database access error occurs
1321 * or this method is called on a closed connection
1322 * @see #getSchema
1323 * @since 1.7
1324 */
1325 void setSchema(String schema) throws SQLException;
1326
1327 /**
1328 * Retrieves this <code>Connection</code> object's current schema name.
1329 *
1330 * @return the current schema name or <code>null</code> if there is none
1331 * @exception SQLException if a database access error occurs
1332 * or this method is called on a closed connection
1333 * @see #setSchema
1334 * @since 1.7
1335 */
1336 String getSchema() throws SQLException;
1337
1338 /**
1339 * Terminates an open connection. Calling <code>abort</code> results in:
1340 * <ul>
1341 * <li>The connection marked as closed
1342 * <li>Closes any physical connection to the database
1343 * <li>Releases resources used by the connection
1344 * <li>Insures that any thread that is currently accessing the connection
1345 * will either progress to completion or throw an <code>SQLException</code>.
1346 * </ul>
1347 * <p>
1348 * Calling <code>abort</code> marks the connection closed and releases any
1349 * resources. Calling <code>abort</code> on a closed connection is a
1350 * no-op.
1351 * <p>
1352 * It is possible that the aborting and releasing of the resources that are
1353 * held by the connection can take an extended period of time. When the
1354 * <code>abort</code> method returns, the connection will have been marked as
1355 * closed and the <code>Executor</code> that was passed as a parameter to abort
1356 * may still be executing tasks to release resources.
1357 * <p>
1358 * This method checks to see that there is an <code>SQLPermission</code>
1359 * object before allowing the method to proceed. If a
1360 * <code>SecurityManager</code> exists and its
1361 * <code>checkPermission</code> method denies calling <code>abort</code>,
1362 * this method throws a
1363 * <code>java.lang.SecurityException</code>.
1364 * @param executor The <code>Executor</code> implementation which will
1365 * be used by <code>abort</code>.
1366 * @throws java.sql.SQLException if a database access error occurs or
1367 * the {@code executor} is {@code null},
1368 * @throws java.lang.SecurityException if a security manager exists and its
1369 * <code>checkPermission</code> method denies calling <code>abort</code>
1370 * @see SecurityManager#checkPermission
1371 * @see Executor
1372 * @since 1.7
1373 */
1374 void abort(Executor executor) throws SQLException;
1375
1376 /**
1377 *
1378 * Sets the maximum period a <code>Connection</code> or
1379 * objects created from the <code>Connection</code>
1380 * will wait for the database to reply to any one request. If any
1381 * request remains unanswered, the waiting method will
1382 * return with a <code>SQLException</code>, and the <code>Connection</code>
1383 * or objects created from the <code>Connection</code> will be marked as
1384 * closed. Any subsequent use of
1385 * the objects, with the exception of the <code>close</code>,
1386 * <code>isClosed</code> or <code>Connection.isValid</code>
1387 * methods, will result in a <code>SQLException</code>.
1388 * <p>
1389 * <b>Note</b>: This method is intended to address a rare but serious
1390 * condition where network partitions can cause threads issuing JDBC calls
1391 * to hang uninterruptedly in socket reads, until the OS TCP-TIMEOUT
1392 * (typically 10 minutes). This method is related to the
1393 * {@link #abort abort() } method which provides an administrator
1394 * thread a means to free any such threads in cases where the
1395 * JDBC connection is accessible to the administrator thread.
1396 * The <code>setNetworkTimeout</code> method will cover cases where
1397 * there is no administrator thread, or it has no access to the
1398 * connection. This method is severe in it's effects, and should be
1399 * given a high enough value so it is never triggered before any more
1400 * normal timeouts, such as transaction timeouts.
1401 * <p>
1402 * JDBC driver implementations may also choose to support the
1403 * {@code setNetworkTimeout} method to impose a limit on database
1404 * response time, in environments where no network is present.
1405 * <p>
1406 * Drivers may internally implement some or all of their API calls with
1407 * multiple internal driver-database transmissions, and it is left to the
1408 * driver implementation to determine whether the limit will be
1409 * applied always to the response to the API call, or to any
1410 * single request made during the API call.
1411 * <p>
1412 *
1413 * This method can be invoked more than once, such as to set a limit for an
1414 * area of JDBC code, and to reset to the default on exit from this area.
1415 * Invocation of this method has no impact on already outstanding
1416 * requests.
1417 * <p>
1418 * The {@code Statement.setQueryTimeout()} timeout value is independent of the
1419 * timeout value specified in {@code setNetworkTimeout}. If the query timeout
1420 * expires before the network timeout then the
1421 * statement execution will be canceled. If the network is still
1422 * active the result will be that both the statement and connection
1423 * are still usable. However if the network timeout expires before
1424 * the query timeout or if the statement timeout fails due to network
1425 * problems, the connection will be marked as closed, any resources held by
1426 * the connection will be released and both the connection and
1427 * statement will be unusable.
1428 * <p>
1429 * When the driver determines that the {@code setNetworkTimeout} timeout
1430 * value has expired, the JDBC driver marks the connection
1431 * closed and releases any resources held by the connection.
1432 * <p>
1433 *
1434 * This method checks to see that there is an <code>SQLPermission</code>
1435 * object before allowing the method to proceed. If a
1436 * <code>SecurityManager</code> exists and its
1437 * <code>checkPermission</code> method denies calling
1438 * <code>setNetworkTimeout</code>, this method throws a
1439 * <code>java.lang.SecurityException</code>.
1440 *
1441 * @param executor The <code>Executor</code> implementation which will
1442 * be used by <code>setNetworkTimeout</code>.
1443 * @param milliseconds The time in milliseconds to wait for the database
1444 * operation
1445 * to complete. If the JDBC driver does not support milliseconds, the
1446 * JDBC driver will round the value up to the nearest second. If the
1447 * timeout period expires before the operation
1448 * completes, a SQLException will be thrown.
1449 * A value of 0 indicates that there is not timeout for database operations.
1450 * @throws java.sql.SQLException if a database access error occurs, this
1451 * method is called on a closed connection,
1452 * the {@code executor} is {@code null},
1453 * or the value specified for <code>seconds</code> is less than 0.
1454 * @throws java.lang.SecurityException if a security manager exists and its
1455 * <code>checkPermission</code> method denies calling
1456 * <code>setNetworkTimeout</code>.
1457 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1458 * this method
1459 * @see SecurityManager#checkPermission
1460 * @see Statement#setQueryTimeout
1461 * @see #getNetworkTimeout
1462 * @see #abort
1463 * @see Executor
1464 * @since 1.7
1465 */
1466 void setNetworkTimeout(Executor executor, int milliseconds) throws SQLException;
1467
1468
1469 /**
1470 * Retrieves the number of milliseconds the driver will
1471 * wait for a database request to complete.
1472 * If the limit is exceeded, a
1473 * <code>SQLException</code> is thrown.
1474 *
1475 * @return the current timeout limit in milliseconds; zero means there is
1476 * no limit
1477 * @throws SQLException if a database access error occurs or
1478 * this method is called on a closed <code>Connection</code>
1479 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1480 * this method
1481 * @see #setNetworkTimeout
1482 * @since 1.7
1483 */
1484 int getNetworkTimeout() throws SQLException;
1485
1486 // JDBC 4.3
1487
1488 /**
1489 * Hints to the driver that a request, an independent unit of work, is beginning
1490 * on this connection. Each request is independent of all other requests
1491 * with regard to state local to the connection either on the client or the
1492 * server. Work done between {@code beginRequest}, {@code endRequest}
1493 * pairs does not depend on any other work done on the connection either as
1494 * part of another request or outside of any request. A request may include multiple
1495 * transactions. There may be dependencies on committed database state as
1496 * that is not local to the connection.
1497 * <p>
1498 * Local state is defined as any state associated with a Connection that is
1499 * local to the current Connection either in the client or the database that
1500 * is not transparently reproducible.
1501 * <p>
1502 * Calls to {@code beginRequest} and {@code endRequest} are not nested.
1503 * Multiple calls to {@code beginRequest} without an intervening call
1504 * to {@code endRequest} is not an error. The first {@code beginRequest} call
1505 * marks the start of the request and subsequent calls are treated as
1506 * a no-op
1507 * <p>
1508 * Use of {@code beginRequest} and {@code endRequest} is optional, vendor
1509 * specific and should largely be transparent. In particular
1510 * implementations may detect conditions that indicate dependence on
1511 * other work such as an open transaction. It is recommended though not
1512 * required that implementations throw a {@code SQLException} if there is an active
1513 * transaction and {@code beginRequest} is called.
1514 * Using these methods may improve performance or provide other benefits.
1515 * Consult your vendors documentation for additional information.
1516 * <p>
1517 * It is recommended to
1518 * enclose each unit of work in {@code beginRequest}, {@code endRequest}
1519 * pairs such that there is no open transaction at the beginning or end of
1520 * the request and no dependency on local state that crosses request
1521 * boundaries. Committed database state is not local.
1522 *
1523 * @implSpec
1524 * The default implementation is a no-op.
1525 * <p>
1526 * @apiNote
1527 * This method is to be used by Connection pooling managers.
1528 * <p>
1529 * The pooling manager should call {@code beginRequest} on the underlying connection
1530 * prior to returning a connection to the caller.
1531 * <p>
1532 * The pooling manager does not need to call {@code beginRequest} if:
1533 * <ul>
1534 * <li>The connection pool caches {@code PooledConnection} objects</li>
1535 * <li>Returns a logical connection handle when {@code getConnection} is
1536 * called by the application</li>
1537 * <li>The pool manager calls {@code Connection.close} on the logical connection handle
1538 * prior to returning the {@code PooledConnection} back to the cache</li>
1539 * </ul>
1540 * @throws SQLException if an error occurs
1541 * @since 9
1542 * @see endRequest
1543 * @see javax.sql.PooledConnection
1544 */
1545 default void beginRequest() throws SQLException {
1546 // Default method takes no action
1547 }
1548
1549 /**
1550 * Hints to the driver that a request, an independent unit of work,
1551 * has completed. Calls to {@code beginRequest}
1552 * and {@code endRequest} are not nested. Multiple
1553 * calls to {@code endRequest} without an intervening call to {@code beginRequest}
1554 * is not an error. The first {@code endRequest} call
1555 * marks the request completed and subsequent calls are treated as
1556 * a no-op. If {@code endRequest} is called without an initial call to
1557 * {@code beginRequest} is a no-op.
1558 *<p>
1559 * The exact behavior of this method is vendor specific. In particular
1560 * implementations may detect conditions that indicate dependence on
1561 * other work such as an open transaction. It is recommended though not
1562 * required that implementations throw a {@code SQLException} if there is an active
1563 * transaction and {@code endRequest} is called.
1564 *
1565 * @implSpec
1566 * The default implementation is a no-op.
1567 * @apiNote
1568 *
1569 * This method is to be used by Connection pooling managers.
1570 * <p>
1571 * The pooling manager should call {@code endRequest} on the underlying connection
1572 * when the applications returns the connection back to the connection pool.
1573 * <p>
1574 * The pooling manager does not need to call {@code endRequest} if:
1575 * <ul>
1576 * <li>The connection pool caches {@code PooledConnection} objects</li>
1577 * <li>Returns a logical connection handle when {@code getConnection} is
1578 * called by the application</li>
1579 * <li>The pool manager calls {@code Connection.close} on the logical connection handle
1580 * prior to returning the {@code PooledConnection} back to the cache</li>
1581 * </ul>
1582 * @throws SQLException if an error occurs
1583 * @since 9
1584 * @see beginRequest
1585 * @see javax.sql.PooledConnection
1586 */
1587 default void endRequest() throws SQLException {
1588 // Default method takes no action
1589 }
1590
1591 /**
1592 * Sets and validates the sharding keys for this connection.
1593 * @implSpec
1594 * The default implementation will throw a
1595 * {@code SQLFeatureNotSupportedException}.
1596 *
1597 * @apiNote
1598 * This method validates that the sharding keys are valid for the
1599 * {@code Connection}. The timeout value indicates how long the driver
1600 * should wait for the {@code Connection} to verify that the sharding key
1601 * is valid before {@code setShardingKeyIfValid} returns false.
1602 * @param shardingKey the sharding key to be validated against this connection
1603 * @param superShardingKey the super sharding key to be validated against this
1604 * connection. The super sharding key may be {@code null}.
1605 * @param timeout time in seconds before which the validation process is expected to
1606 * be completed, otherwise the validation process is aborted. A value of 0 indicates
1607 * the validation process will not time out.
1608 * @return true if the connection is valid and the sharding keys are valid
1609 * and set on this connection; false if the sharding keys are not valid or
1610 * the timeout period expires before the operation completes.
1611 * @throws SQLException if an error occurs while performing this validation;
1612 * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified
1613 * without a {@code shardingKey};
1614 * this method is called on a closed {@code connection}; or
1615 * the {@code timeout} value is less than 0.
1616 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1617 * @since 9
1618 * @see ShardingKey
1619 * @see ShardingKeyBuilder
1620 */
1621 default boolean setShardingKeyIfValid(ShardingKey shardingKey,
1622 ShardingKey superShardingKey, int timeout)
1623 throws SQLException {
1624 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
1625 }
1626
1627 /**
1628 * Sets and validates the sharding key for this connection.
1629 * @implSpec
1630 * The default implementation will throw a
1631 * {@code SQLFeatureNotSupportedException}.
1632 * @apiNote
1633 * This method validates that the sharding key is valid for the
1634 * {@code Connection}. The timeout value indicates how long the driver
1635 * should wait for the {@code Connection} to verify that the sharding key
1636 * is valid before {@code setShardingKeyIfValid} returns false.
1637 * @param shardingKey the sharding key to be validated against this connection
1638 * @param timeout time in seconds before which the validation process is expected to
1639 * be completed,else the validation process is aborted. A value of 0 indicates
1640 * the validation process will not time out.
1641 * @return true if the connection is valid and the sharding key is valid to be
1642 * set on this connection; false if the sharding key is not valid or
1643 * the timeout period expires before the operation completes.
1644 * @throws SQLException if there is an error while performing this validation;
1645 * this method is called on a closed {@code connection}; the {@code shardingkey}
1646 * is {@code null}; or the {@code timeout} value is less than 0.
1647 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1648 * @since 9
1649 * @see ShardingKey
1650 * @see ShardingKeyBuilder
1651 */
1652 default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout)
1653 throws SQLException {
1654 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
1655 }
1656
1657 /**
1658 * Specifies a shardingKey and superShardingKey to use with this Connection
1659 * @implSpec
1660 * The default implementation will throw a
1661 * {@code SQLFeatureNotSupportedException}.
1662 * @apiNote
1663 * This method sets the specified sharding keys but does not require a
1664 * round trip to the database to validate that the sharding keys are valid
1665 * for the {@code Connection}.
1666 * @param shardingKey the sharding key to set on this connection.
1667 * @param superShardingKey the super sharding key to set on this connection.
1668 * The super sharding key may be {@code null}
1669 * @throws SQLException if an error occurs setting the sharding keys;
1670 * this method is called on a closed {@code connection};
1671 * the {@code shardingkey} is {@code null}; or
1672 * a {@code superSharedingKey} is specified without a {@code shardingKey}
1673 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1674 * @since 9
1675 * @see ShardingKey
1676 * @see ShardingKeyBuilder
1677 */
1678 default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)
1679 throws SQLException {
1680 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
1681 }
1682
1683 /**
1684 * Specifies a shardingKey to use with this Connection
1685 * @implSpec
1686 * The default implementation will throw a
1687 * {@code SQLFeatureNotSupportedException}.
1688 * @apiNote
1689 * This method sets the specified sharding key but does not require a
1690 * round trip to the database to validate that the sharding key is valid
1691 * for the {@code Connection}.
1692 * @param shardingKey the sharding key to set on this connection.
1693 * @throws SQLException if an error occurs setting the sharding key;
1694 * this method is called on a closed {@code connection}; or the
1695 * {@code shardkingKey} is {@code null}
1696 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1697 * @since 9
1698 * @see ShardingKey
1699 * @see ShardingKeyBuilder
1700 */
1701 default void setShardingKey(ShardingKey shardingKey)
1702 throws SQLException {
1703 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
1704 }
1705 }