1 /*
2 * Copyright 1996-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.sql;
27
28 import java.util.Properties;
29
30 /**
31 * <P>A connection (session) with a specific
32 * database. SQL statements are executed and results are returned
33 * within the context of a connection.
34 * <P>
35 * A <code>Connection</code> object's database is able to provide information
36 * describing its tables, its supported SQL grammar, its stored
37 * procedures, the capabilities of this connection, and so on. This
38 * information is obtained with the <code>getMetaData</code> method.
39 *
40 * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications
41 * should use the appropritate <code>Connection</code> method such as
42 * <code>setAutoCommit</code> or <code>setTransactionIsolation</code>.
43 * Applications should not invoke SQL commands directly to change the connection's
44 * configuration when there is a JDBC method available. By default a <code>Connection</code> object is in
45 * auto-commit mode, which means that it automatically commits changes
46 * after executing each statement. If auto-commit mode has been
47 * disabled, the method <code>commit</code> must be called explicitly in
48 * order to commit changes; otherwise, database changes will not be saved.
49 * <P>
50 * A new <code>Connection</code> object created using the JDBC 2.1 core API
51 * has an initially empty type map associated with it. A user may enter a
52 * custom mapping for a UDT in this type map.
53 * When a UDT is retrieved from a data source with the
54 * method <code>ResultSet.getObject</code>, the <code>getObject</code> method
55 * will check the connection's type map to see if there is an entry for that
56 * UDT. If so, the <code>getObject</code> method will map the UDT to the
57 * class indicated. If there is no entry, the UDT will be mapped using the
58 * standard mapping.
59 * <p>
60 * A user may create a new type map, which is a <code>java.util.Map</code>
61 * object, make an entry in it, and pass it to the <code>java.sql</code>
62 * methods that can perform custom mapping. In this case, the method
63 * will use the given type map instead of the one associated with
64 * the connection.
65 * <p>
66 * For example, the following code fragment specifies that the SQL
67 * type <code>ATHLETES</code> will be mapped to the class
68 * <code>Athletes</code> in the Java programming language.
69 * The code fragment retrieves the type map for the <code>Connection
70 * </code> object <code>con</code>, inserts the entry into it, and then sets
71 * the type map with the new entry as the connection's type map.
72 * <pre>
73 * java.util.Map map = con.getTypeMap();
74 * map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
75 * con.setTypeMap(map);
76 * </pre>
77 *
78 * @see DriverManager#getConnection
79 * @see Statement
80 * @see ResultSet
81 * @see DatabaseMetaData
82 */
83 public interface Connection extends Wrapper {
84
85 /**
86 * Creates a <code>Statement</code> object for sending
87 * SQL statements to the database.
88 * SQL statements without parameters are normally
89 * executed using <code>Statement</code> objects. If the same SQL statement
90 * is executed many times, it may be more efficient to use a
91 * <code>PreparedStatement</code> object.
92 * <P>
93 * Result sets created using the returned <code>Statement</code>
94 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
95 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
96 * The holdability of the created result sets can be determined by
97 * calling {@link #getHoldability}.
98 *
99 * @return a new default <code>Statement</code> object
100 * @exception SQLException if a database access error occurs
101 * or this method is called on a closed connection
102 */
103 Statement createStatement() throws SQLException;
104
105 /**
106 * Creates a <code>PreparedStatement</code> object for sending
107 * parameterized SQL statements to the database.
108 * <P>
109 * A SQL statement with or without IN parameters can be
110 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
111 * object can then be used to efficiently execute this statement
112 * multiple times.
113 *
114 * <P><B>Note:</B> This method is optimized for handling
115 * parametric SQL statements that benefit from precompilation. If
116 * the driver supports precompilation,
117 * the method <code>prepareStatement</code> will send
118 * the statement to the database for precompilation. Some drivers
119 * may not support precompilation. In this case, the statement may
120 * not be sent to the database until the <code>PreparedStatement</code>
121 * object is executed. This has no direct effect on users; however, it does
122 * affect which methods throw certain <code>SQLException</code> objects.
123 * <P>
124 * Result sets created using the returned <code>PreparedStatement</code>
125 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
126 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
127 * The holdability of the created result sets can be determined by
128 * calling {@link #getHoldability}.
129 *
130 * @param sql an SQL statement that may contain one or more '?' IN
131 * parameter placeholders
132 * @return a new default <code>PreparedStatement</code> object containing the
133 * pre-compiled SQL statement
134 * @exception SQLException if a database access error occurs
135 * or this method is called on a closed connection
136 */
137 PreparedStatement prepareStatement(String sql)
138 throws SQLException;
139
140 /**
141 * Creates a <code>CallableStatement</code> object for calling
142 * database stored procedures.
143 * The <code>CallableStatement</code> object provides
144 * methods for setting up its IN and OUT parameters, and
145 * methods for executing the call to a stored procedure.
146 *
147 * <P><B>Note:</B> This method is optimized for handling stored
148 * procedure call statements. Some drivers may send the call
149 * statement to the database when the method <code>prepareCall</code>
150 * is done; others
151 * may wait until the <code>CallableStatement</code> object
152 * is executed. This has no
153 * direct effect on users; however, it does affect which method
154 * throws certain SQLExceptions.
155 * <P>
156 * Result sets created using the returned <code>CallableStatement</code>
157 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
158 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
159 * The holdability of the created result sets can be determined by
160 * calling {@link #getHoldability}.
161 *
162 * @param sql an SQL statement that may contain one or more '?'
163 * parameter placeholders. Typically this statement is specified using JDBC
164 * call escape syntax.
165 * @return a new default <code>CallableStatement</code> object containing the
166 * pre-compiled SQL statement
167 * @exception SQLException if a database access error occurs
168 * or this method is called on a closed connection
169 */
170 CallableStatement prepareCall(String sql) throws SQLException;
171
172 /**
173 * Converts the given SQL statement into the system's native SQL grammar.
174 * A driver may convert the JDBC SQL grammar into its system's
175 * native SQL grammar prior to sending it. This method returns the
176 * native form of the statement that the driver would have sent.
177 *
178 * @param sql an SQL statement that may contain one or more '?'
179 * parameter placeholders
180 * @return the native form of this statement
181 * @exception SQLException if a database access error occurs
182 * or this method is called on a closed connection
183 */
184 String nativeSQL(String sql) throws SQLException;
185
186 /**
187 * Sets this connection's auto-commit mode to the given state.
188 * If a connection is in auto-commit mode, then all its SQL
189 * statements will be executed and committed as individual
190 * transactions. Otherwise, its SQL statements are grouped into
191 * transactions that are terminated by a call to either
192 * the method <code>commit</code> or the method <code>rollback</code>.
193 * By default, new connections are in auto-commit
194 * mode.
195 * <P>
196 * The commit occurs when the statement completes. The time when the statement
197 * completes depends on the type of SQL Statement:
198 * <ul>
199 * <li>For DML statements, such as Insert, Update or Delete, and DDL statements,
200 * the statement is complete as soon as it has finished executing.
201 * <li>For Select statements, the statement is complete when the associated result
202 * set is closed.
203 * <li>For <code>CallableStatement</code> objects or for statements that return
204 * multiple results, the statement is complete
205 * when all of the associated result sets have been closed, and all update
206 * counts and output parameters have been retrieved.
207 *</ul>
208 * <P>
209 * <B>NOTE:</B> If this method is called during a transaction and the
210 * auto-commit mode is changed, the transaction is committed. If
211 * <code>setAutoCommit</code> is called and the auto-commit mode is
212 * not changed, the call is a no-op.
213 *
214 * @param autoCommit <code>true</code> to enable auto-commit mode;
215 * <code>false</code> to disable it
216 * @exception SQLException if a database access error occurs,
217 * setAutoCommit(true) is called while participating in a distributed transaction,
218 * or this method is called on a closed connection
219 * @see #getAutoCommit
220 */
221 void setAutoCommit(boolean autoCommit) throws SQLException;
222
223 /**
224 * Retrieves the current auto-commit mode for this <code>Connection</code>
225 * object.
226 *
227 * @return the current state of this <code>Connection</code> object's
228 * auto-commit mode
229 * @exception SQLException if a database access error occurs
230 * or this method is called on a closed connection
231 * @see #setAutoCommit
232 */
233 boolean getAutoCommit() throws SQLException;
234
235 /**
236 * Makes all changes made since the previous
237 * commit/rollback permanent and releases any database locks
238 * currently held by this <code>Connection</code> object.
239 * This method should be
240 * used only when auto-commit mode has been disabled.
241 *
242 * @exception SQLException if a database access error occurs,
243 * this method is called while participating in a distributed transaction,
244 * if this method is called on a closed conection or this
245 * <code>Connection</code> object is in auto-commit mode
246 * @see #setAutoCommit
247 */
248 void commit() throws SQLException;
249
250 /**
251 * Undoes all changes made in the current transaction
252 * and releases any database locks currently held
253 * by this <code>Connection</code> object. This method should be
254 * used only when auto-commit mode has been disabled.
255 *
256 * @exception SQLException if a database access error occurs,
257 * this method is called while participating in a distributed transaction,
258 * this method is called on a closed connection or this
259 * <code>Connection</code> object is in auto-commit mode
260 * @see #setAutoCommit
261 */
262 void rollback() throws SQLException;
263
264 /**
265 * Releases this <code>Connection</code> object's database and JDBC resources
266 * immediately instead of waiting for them to be automatically released.
267 * <P>
268 * Calling the method <code>close</code> on a <code>Connection</code>
269 * object that is already closed is a no-op.
270 * <P>
271 * It is <b>strongly recommended</b> that an application explicitly
272 * commits or rolls back an active transaction prior to calling the
273 * <code>close</code> method. If the <code>close</code> method is called
274 * and there is an active transaction, the results are implementation-defined.
275 * <P>
276 *
277 * @exception SQLException 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 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 *
351 * @param catalog the name of a catalog (subspace in this
352 * <code>Connection</code> object's database) in which to work
353 * @exception SQLException if a database access error occurs
354 * or this method is called on a closed connection
355 * @see #getCatalog
356 */
357 void setCatalog(String catalog) throws SQLException;
358
359 /**
360 * Retrieves this <code>Connection</code> object's current catalog name.
361 *
362 * @return the current catalog name or <code>null</code> if there is none
363 * @exception SQLException if a database access error occurs
364 * or this method is called on a closed connection
365 * @see #setCatalog
366 */
367 String getCatalog() throws SQLException;
368
369 /**
370 * A constant indicating that transactions are not supported.
371 */
372 int TRANSACTION_NONE = 0;
373
374 /**
375 * A constant indicating that
376 * dirty reads, non-repeatable reads and phantom reads can occur.
377 * This level allows a row changed by one transaction to be read
378 * by another transaction before any changes in that row have been
379 * committed (a "dirty read"). If any of the changes are rolled back,
380 * the second transaction will have retrieved an invalid row.
381 */
382 int TRANSACTION_READ_UNCOMMITTED = 1;
383
384 /**
385 * A constant indicating that
386 * dirty reads are prevented; non-repeatable reads and phantom
387 * reads can occur. This level only prohibits a transaction
388 * from reading a row with uncommitted changes in it.
389 */
390 int TRANSACTION_READ_COMMITTED = 2;
391
392 /**
393 * A constant indicating that
394 * dirty reads and non-repeatable reads are prevented; phantom
395 * reads can occur. This level prohibits a transaction from
396 * reading a row with uncommitted changes in it, and it also
397 * prohibits the situation where one transaction reads a row,
398 * a second transaction alters the row, and the first transaction
399 * rereads the row, getting different values the second time
400 * (a "non-repeatable read").
401 */
402 int TRANSACTION_REPEATABLE_READ = 4;
403
404 /**
405 * A constant indicating that
406 * dirty reads, non-repeatable reads and phantom reads are prevented.
407 * This level includes the prohibitions in
408 * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the
409 * situation where one transaction reads all rows that satisfy
410 * a <code>WHERE</code> condition, a second transaction inserts a row that
411 * satisfies that <code>WHERE</code> condition, and the first transaction
412 * rereads for the same condition, retrieving the additional
413 * "phantom" row in the second read.
414 */
415 int TRANSACTION_SERIALIZABLE = 8;
416
417 /**
418 * Attempts to change the transaction isolation level for this
419 * <code>Connection</code> object to the one given.
420 * The constants defined in the interface <code>Connection</code>
421 * are the possible transaction isolation levels.
422 * <P>
423 * <B>Note:</B> If this method is called during a transaction, the result
424 * is implementation-defined.
425 *
426 * @param level one of the following <code>Connection</code> constants:
427 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
428 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
429 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
430 * <code>Connection.TRANSACTION_SERIALIZABLE</code>.
431 * (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used
432 * because it specifies that transactions are not supported.)
433 * @exception SQLException if a database access error occurs, this
434 * method is called on a closed connection
435 * or the given parameter is not one of the <code>Connection</code>
436 * constants
437 * @see DatabaseMetaData#supportsTransactionIsolationLevel
438 * @see #getTransactionIsolation
439 */
440 void setTransactionIsolation(int level) throws SQLException;
441
442 /**
443 * Retrieves this <code>Connection</code> object's current
444 * transaction isolation level.
445 *
446 * @return the current transaction isolation level, which will be one
447 * of the following constants:
448 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
449 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
450 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>,
451 * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
452 * <code>Connection.TRANSACTION_NONE</code>.
453 * @exception SQLException if a database access error occurs
454 * or this method is called on a closed connection
455 * @see #setTransactionIsolation
456 */
457 int getTransactionIsolation() throws SQLException;
458
459 /**
460 * Retrieves the first warning reported by calls on this
461 * <code>Connection</code> object. If there is more than one
462 * warning, subsequent warnings will be chained to the first one
463 * and can be retrieved by calling the method
464 * <code>SQLWarning.getNextWarning</code> on the warning
465 * that was retrieved previously.
466 * <P>
467 * This method may not be
468 * called on a closed connection; doing so will cause an
469 * <code>SQLException</code> to be thrown.
470 *
471 * <P><B>Note:</B> Subsequent warnings will be chained to this
472 * SQLWarning.
473 *
474 * @return the first <code>SQLWarning</code> object or <code>null</code>
475 * if there are none
476 * @exception SQLException if a database access error occurs or
477 * this method is called on a closed connection
478 * @see SQLWarning
479 */
480 SQLWarning getWarnings() throws SQLException;
481
482 /**
483 * Clears all warnings reported for this <code>Connection</code> object.
484 * After a call to this method, the method <code>getWarnings</code>
485 * returns <code>null</code> until a new warning is
486 * reported for this <code>Connection</code> object.
487 *
488 * @exception SQLException SQLException if a database access error occurs
489 * or this method is called on a closed connection
490 */
491 void clearWarnings() throws SQLException;
492
493
494 //--------------------------JDBC 2.0-----------------------------
495
496 /**
497 * Creates a <code>Statement</code> object that will generate
498 * <code>ResultSet</code> objects with the given type and concurrency.
499 * This method is the same as the <code>createStatement</code> method
500 * above, but it allows the default result set
501 * type and concurrency to be overridden.
502 * The holdability of the created result sets can be determined by
503 * calling {@link #getHoldability}.
504 *
505 * @param resultSetType a result set type; one of
506 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
507 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
508 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
509 * @param resultSetConcurrency a concurrency type; one of
510 * <code>ResultSet.CONCUR_READ_ONLY</code> or
511 * <code>ResultSet.CONCUR_UPDATABLE</code>
512 * @return a new <code>Statement</code> object that will generate
513 * <code>ResultSet</code> objects with the given type and
514 * concurrency
515 * @exception SQLException if a database access error occurs, this
516 * method is called on a closed connection
517 * or the given parameters are not <code>ResultSet</code>
518 * constants indicating type and concurrency
519 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
520 * this method or this method is not supported for the specified result
521 * set type and result set concurrency.
522 * @since 1.2
523 */
524 Statement createStatement(int resultSetType, int resultSetConcurrency)
525 throws SQLException;
526
527 /**
528 *
529 * Creates a <code>PreparedStatement</code> object that will generate
530 * <code>ResultSet</code> objects with the given type and concurrency.
531 * This method is the same as the <code>prepareStatement</code> method
532 * above, but it allows the default result set
533 * type and concurrency to be overridden.
534 * The holdability of the created result sets can be determined by
535 * calling {@link #getHoldability}.
536 *
537 * @param sql a <code>String</code> object that is the SQL statement to
538 * be sent to the database; may contain one or more '?' IN
539 * parameters
540 * @param resultSetType a result set type; one of
541 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
542 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
543 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
544 * @param resultSetConcurrency a concurrency type; one of
545 * <code>ResultSet.CONCUR_READ_ONLY</code> or
546 * <code>ResultSet.CONCUR_UPDATABLE</code>
547 * @return a new PreparedStatement object containing the
548 * pre-compiled SQL statement that will produce <code>ResultSet</code>
549 * objects with the given type and concurrency
550 * @exception SQLException if a database access error occurs, this
551 * method is called on a closed connection
552 * or the given parameters are not <code>ResultSet</code>
553 * constants indicating type and concurrency
554 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
555 * this method or this method is not supported for the specified result
556 * set type and result set concurrency.
557 * @since 1.2
558 */
559 PreparedStatement prepareStatement(String sql, int resultSetType,
560 int resultSetConcurrency)
561 throws SQLException;
562
563 /**
564 * Creates a <code>CallableStatement</code> object that will generate
565 * <code>ResultSet</code> objects with the given type and concurrency.
566 * This method is the same as the <code>prepareCall</code> method
567 * above, but it allows the default result set
568 * type and concurrency to be overridden.
569 * The holdability of the created result sets can be determined by
570 * calling {@link #getHoldability}.
571 *
572 * @param sql a <code>String</code> object that is the SQL statement to
573 * be sent to the database; may contain on or more '?' parameters
574 * @param resultSetType a result set type; one of
575 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
576 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
577 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
578 * @param resultSetConcurrency a concurrency type; one of
579 * <code>ResultSet.CONCUR_READ_ONLY</code> or
580 * <code>ResultSet.CONCUR_UPDATABLE</code>
581 * @return a new <code>CallableStatement</code> object containing the
582 * pre-compiled SQL statement that will produce <code>ResultSet</code>
583 * objects with the given type and concurrency
584 * @exception SQLException if a database access error occurs, this method
585 * is called on a closed connection
586 * or the given parameters are not <code>ResultSet</code>
587 * constants indicating type and concurrency
588 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
589 * this method or this method is not supported for the specified result
590 * set type and result set concurrency.
591 * @since 1.2
592 */
593 CallableStatement prepareCall(String sql, int resultSetType,
594 int resultSetConcurrency) throws SQLException;
595
596 /**
597 * Retrieves the <code>Map</code> object associated with this
598 * <code>Connection</code> object.
599 * Unless the application has added an entry, the type map returned
600 * will be empty.
601 *
602 * @return the <code>java.util.Map</code> object associated
603 * with this <code>Connection</code> object
604 * @exception SQLException if a database access error occurs
605 * or this method is called on a closed connection
606 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
607 * this method
608 * @since 1.2
609 * @see #setTypeMap
610 */
611 java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
612
613 /**
614 * Installs the given <code>TypeMap</code> object as the type map for
615 * this <code>Connection</code> object. The type map will be used for the
616 * custom mapping of SQL structured types and distinct types.
617 *
618 * @param map the <code>java.util.Map</code> object to install
619 * as the replacement for this <code>Connection</code>
620 * object's default type map
621 * @exception SQLException if a database access error occurs, this
622 * method is called on a closed connection or
623 * the given parameter is not a <code>java.util.Map</code>
624 * object
625 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
626 * this method
627 * @since 1.2
628 * @see #getTypeMap
629 */
630 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
631
632 //--------------------------JDBC 3.0-----------------------------
633
634
635 /**
636 * Changes the default holdability of <code>ResultSet</code> objects
637 * created using this <code>Connection</code> object to the given
638 * holdability. The default holdability of <code>ResultSet</code> objects
639 * can be be determined by invoking
640 * {@link DatabaseMetaData#getResultSetHoldability}.
641 *
642 * @param holdability a <code>ResultSet</code> holdability constant; one of
643 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
644 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
645 * @throws SQLException if a database access occurs, this method is called
646 * on a closed connection, or the given parameter
647 * is not a <code>ResultSet</code> constant indicating holdability
648 * @exception SQLFeatureNotSupportedException if the given holdability is not supported
649 * @see #getHoldability
650 * @see DatabaseMetaData#getResultSetHoldability
651 * @see ResultSet
652 * @since 1.4
653 */
654 void setHoldability(int holdability) throws SQLException;
655
656 /**
657 * Retrieves the current holdability of <code>ResultSet</code> objects
658 * created using this <code>Connection</code> object.
659 *
660 * @return the holdability, one of
661 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
662 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
663 * @throws SQLException if a database access error occurs
664 * or this method is called on a closed connection
665 * @see #setHoldability
666 * @see DatabaseMetaData#getResultSetHoldability
667 * @see ResultSet
668 * @since 1.4
669 */
670 int getHoldability() throws SQLException;
671
672 /**
673 * Creates an unnamed savepoint in the current transaction and
674 * returns the new <code>Savepoint</code> object that represents it.
675 *
676 *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
677 *savepoint.
678 *
679 * @return the new <code>Savepoint</code> object
680 * @exception SQLException if a database access error occurs,
681 * this method is called while participating in a distributed transaction,
682 * this method is called on a closed connection
683 * or this <code>Connection</code> object is currently in
684 * auto-commit mode
685 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
686 * this method
687 * @see Savepoint
688 * @since 1.4
689 */
690 Savepoint setSavepoint() throws SQLException;
691
692 /**
693 * Creates a savepoint with the given name in the current transaction
694 * and returns the new <code>Savepoint</code> object that represents it.
695 *
696 * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
697 *savepoint.
698 *
699 * @param name a <code>String</code> containing the name of the savepoint
700 * @return the new <code>Savepoint</code> object
701 * @exception SQLException if a database access error occurs,
702 * this method is called while participating in a distributed transaction,
703 * this method is called on a closed connection
704 * or this <code>Connection</code> object is currently in
705 * auto-commit mode
706 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
707 * this method
708 * @see Savepoint
709 * @since 1.4
710 */
711 Savepoint setSavepoint(String name) throws SQLException;
712
713 /**
714 * Undoes all changes made after the given <code>Savepoint</code> object
715 * was set.
716 * <P>
717 * This method should be used only when auto-commit has been disabled.
718 *
719 * @param savepoint the <code>Savepoint</code> object to roll back to
720 * @exception SQLException if a database access error occurs,
721 * this method is called while participating in a distributed transaction,
722 * this method is called on a closed connection,
723 * the <code>Savepoint</code> object is no longer valid,
724 * or this <code>Connection</code> object is currently in
725 * auto-commit mode
726 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
727 * this method
728 * @see Savepoint
729 * @see #rollback
730 * @since 1.4
731 */
732 void rollback(Savepoint savepoint) throws SQLException;
733
734 /**
735 * Removes the specified <code>Savepoint</code> and subsequent <code>Savepoint</code> objects from the current
736 * transaction. Any reference to the savepoint after it have been removed
737 * will cause an <code>SQLException</code> to be thrown.
738 *
739 * @param savepoint the <code>Savepoint</code> object to be removed
740 * @exception SQLException if a database access error occurs, this
741 * method is called on a closed connection or
742 * the given <code>Savepoint</code> object is not a valid
743 * savepoint in the current transaction
744 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
745 * this method
746 * @since 1.4
747 */
748 void releaseSavepoint(Savepoint savepoint) throws SQLException;
749
750 /**
751 * Creates a <code>Statement</code> object that will generate
752 * <code>ResultSet</code> objects with the given type, concurrency,
753 * and holdability.
754 * This method is the same as the <code>createStatement</code> method
755 * above, but it allows the default result set
756 * type, concurrency, and holdability to be overridden.
757 *
758 * @param resultSetType one of the following <code>ResultSet</code>
759 * constants:
760 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
761 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
762 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
763 * @param resultSetConcurrency one of the following <code>ResultSet</code>
764 * constants:
765 * <code>ResultSet.CONCUR_READ_ONLY</code> or
766 * <code>ResultSet.CONCUR_UPDATABLE</code>
767 * @param resultSetHoldability one of the following <code>ResultSet</code>
768 * constants:
769 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
770 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
771 * @return a new <code>Statement</code> object that will generate
772 * <code>ResultSet</code> objects with the given type,
773 * concurrency, and holdability
774 * @exception SQLException if a database access error occurs, this
775 * method is called on a closed connection
776 * or the given parameters are not <code>ResultSet</code>
777 * constants indicating type, concurrency, and holdability
778 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
779 * this method or this method is not supported for the specified result
780 * set type, result set holdability and result set concurrency.
781 * @see ResultSet
782 * @since 1.4
783 */
784 Statement createStatement(int resultSetType, int resultSetConcurrency,
785 int resultSetHoldability) throws SQLException;
786
787 /**
788 * Creates a <code>PreparedStatement</code> object that will generate
789 * <code>ResultSet</code> objects with the given type, concurrency,
790 * and holdability.
791 * <P>
792 * This method is the same as the <code>prepareStatement</code> method
793 * above, but it allows the default result set
794 * type, concurrency, and holdability to be overridden.
795 *
796 * @param sql a <code>String</code> object that is the SQL statement to
797 * be sent to the database; may contain one or more '?' IN
798 * parameters
799 * @param resultSetType one of the following <code>ResultSet</code>
800 * constants:
801 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
802 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
803 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
804 * @param resultSetConcurrency one of the following <code>ResultSet</code>
805 * constants:
806 * <code>ResultSet.CONCUR_READ_ONLY</code> or
807 * <code>ResultSet.CONCUR_UPDATABLE</code>
808 * @param resultSetHoldability one of the following <code>ResultSet</code>
809 * constants:
810 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
811 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
812 * @return a new <code>PreparedStatement</code> object, containing the
813 * pre-compiled SQL statement, that will generate
814 * <code>ResultSet</code> objects with the given type,
815 * concurrency, and holdability
816 * @exception SQLException if a database access error occurs, this
817 * method is called on a closed connection
818 * or the given parameters are not <code>ResultSet</code>
819 * constants indicating type, concurrency, and holdability
820 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
821 * this method or this method is not supported for the specified result
822 * set type, result set holdability and result set concurrency.
823 * @see ResultSet
824 * @since 1.4
825 */
826 PreparedStatement prepareStatement(String sql, int resultSetType,
827 int resultSetConcurrency, int resultSetHoldability)
828 throws SQLException;
829
830 /**
831 * Creates a <code>CallableStatement</code> object that will generate
832 * <code>ResultSet</code> objects with the given type and concurrency.
833 * This method is the same as the <code>prepareCall</code> method
834 * above, but it allows the default result set
835 * type, result set concurrency type and holdability to be overridden.
836 *
837 * @param sql a <code>String</code> object that is the SQL statement to
838 * be sent to the database; may contain on or more '?' parameters
839 * @param resultSetType one of the following <code>ResultSet</code>
840 * constants:
841 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
842 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
843 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
844 * @param resultSetConcurrency one of the following <code>ResultSet</code>
845 * constants:
846 * <code>ResultSet.CONCUR_READ_ONLY</code> or
847 * <code>ResultSet.CONCUR_UPDATABLE</code>
848 * @param resultSetHoldability one of the following <code>ResultSet</code>
849 * constants:
850 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
851 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
852 * @return a new <code>CallableStatement</code> object, containing the
853 * pre-compiled SQL statement, that will generate
854 * <code>ResultSet</code> objects with the given type,
855 * concurrency, and holdability
856 * @exception SQLException if a database access error occurs, this
857 * method is called on a closed connection
858 * or the given parameters are not <code>ResultSet</code>
859 * constants indicating type, concurrency, and holdability
860 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
861 * this method or this method is not supported for the specified result
862 * set type, result set holdability and result set concurrency.
863 * @see ResultSet
864 * @since 1.4
865 */
866 CallableStatement prepareCall(String sql, int resultSetType,
867 int resultSetConcurrency,
868 int resultSetHoldability) throws SQLException;
869
870
871 /**
872 * Creates a default <code>PreparedStatement</code> object that has
873 * the capability to retrieve auto-generated keys. The given constant
874 * tells the driver whether it should make auto-generated keys
875 * available for retrieval. This parameter is ignored if the SQL statement
876 * is not an <code>INSERT</code> statement, or an SQL statement able to return
877 * auto-generated keys (the list of such statements is vendor-specific).
878 * <P>
879 * <B>Note:</B> This method is optimized for handling
880 * parametric SQL statements that benefit from precompilation. If
881 * the driver supports precompilation,
882 * the method <code>prepareStatement</code> will send
883 * the statement to the database for precompilation. Some drivers
884 * may not support precompilation. In this case, the statement may
885 * not be sent to the database until the <code>PreparedStatement</code>
886 * object is executed. This has no direct effect on users; however, it does
887 * affect which methods throw certain SQLExceptions.
888 * <P>
889 * Result sets created using the returned <code>PreparedStatement</code>
890 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
891 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
892 * The holdability of the created result sets can be determined by
893 * calling {@link #getHoldability}.
894 *
895 * @param sql an SQL statement that may contain one or more '?' IN
896 * parameter placeholders
897 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
898 * should be returned; one of
899 * <code>Statement.RETURN_GENERATED_KEYS</code> or
900 * <code>Statement.NO_GENERATED_KEYS</code>
901 * @return a new <code>PreparedStatement</code> object, containing the
902 * pre-compiled SQL statement, that will have the capability of
903 * returning auto-generated keys
904 * @exception SQLException if a database access error occurs, this
905 * method is called on a closed connection
906 * or the given parameter is not a <code>Statement</code>
907 * constant indicating whether auto-generated keys should be
908 * returned
909 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
910 * this method with a constant of Statement.RETURN_GENERATED_KEYS
911 * @since 1.4
912 */
913 PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
914 throws SQLException;
915
916 /**
917 * Creates a default <code>PreparedStatement</code> object capable
918 * of returning the auto-generated keys designated by the given array.
919 * This array contains the indexes of the columns in the target
920 * table that contain the auto-generated keys that should be made
921 * available. The driver will ignore the array if the SQL statement
922 * is not an <code>INSERT</code> statement, or an SQL statement able to return
923 * auto-generated keys (the list of such statements is vendor-specific).
924 *<p>
925 * An SQL statement with or without IN parameters can be
926 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
927 * object can then be used to efficiently execute this statement
928 * multiple times.
929 * <P>
930 * <B>Note:</B> This method is optimized for handling
931 * parametric SQL statements that benefit from precompilation. If
932 * the driver supports precompilation,
933 * the method <code>prepareStatement</code> will send
934 * the statement to the database for precompilation. Some drivers
935 * may not support precompilation. In this case, the statement may
936 * not be sent to the database until the <code>PreparedStatement</code>
937 * object is executed. This has no direct effect on users; however, it does
938 * affect which methods throw certain SQLExceptions.
939 * <P>
940 * Result sets created using the returned <code>PreparedStatement</code>
941 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
942 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
943 * The holdability of the created result sets can be determined by
944 * calling {@link #getHoldability}.
945 *
946 * @param sql an SQL statement that may contain one or more '?' IN
947 * parameter placeholders
948 * @param columnIndexes an array of column indexes indicating the columns
949 * that should be returned from the inserted row or rows
950 * @return a new <code>PreparedStatement</code> object, containing the
951 * pre-compiled statement, that is capable of returning the
952 * auto-generated keys designated by the given array of column
953 * indexes
954 * @exception SQLException if a database access error occurs
955 * or this method is called on a closed connection
956 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
957 * this method
958 *
959 * @since 1.4
960 */
961 PreparedStatement prepareStatement(String sql, int columnIndexes[])
962 throws SQLException;
963
964 /**
965 * Creates a default <code>PreparedStatement</code> object capable
966 * of returning the auto-generated keys designated by the given array.
967 * This array contains the names of the columns in the target
968 * table that contain the auto-generated keys that should be returned.
969 * The driver will ignore the array if the SQL statement
970 * is not an <code>INSERT</code> statement, or an SQL statement able to return
971 * auto-generated keys (the list of such statements is vendor-specific).
972 * <P>
973 * An SQL statement with or without IN parameters can be
974 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
975 * object can then be used to efficiently execute this statement
976 * multiple times.
977 * <P>
978 * <B>Note:</B> This method is optimized for handling
979 * parametric SQL statements that benefit from precompilation. If
980 * the driver supports precompilation,
981 * the method <code>prepareStatement</code> will send
982 * the statement to the database for precompilation. Some drivers
983 * may not support precompilation. In this case, the statement may
984 * not be sent to the database until the <code>PreparedStatement</code>
985 * object is executed. This has no direct effect on users; however, it does
986 * affect which methods throw certain SQLExceptions.
987 * <P>
988 * Result sets created using the returned <code>PreparedStatement</code>
989 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
990 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
991 * The holdability of the created result sets can be determined by
992 * calling {@link #getHoldability}.
993 *
994 * @param sql an SQL statement that may contain one or more '?' IN
995 * parameter placeholders
996 * @param columnNames an array of column names indicating the columns
997 * that should be returned from the inserted row or rows
998 * @return a new <code>PreparedStatement</code> object, containing the
999 * pre-compiled statement, that is capable of returning the
1000 * auto-generated keys designated by the given array of column
1001 * names
1002 * @exception SQLException if a database access error occurs
1003 * or this method is called on a closed connection
1004 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1005 * this method
1006 *
1007 * @since 1.4
1008 */
1009 PreparedStatement prepareStatement(String sql, String columnNames[])
1010 throws SQLException;
1011
1012 /**
1013 * Constructs an object that implements the <code>Clob</code> interface. The object
1014 * returned initially contains no data. The <code>setAsciiStream</code>,
1015 * <code>setCharacterStream</code> and <code>setString</code> methods of
1016 * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>.
1017 * @return An object that implements the <code>Clob</code> interface
1018 * @throws SQLException if an object that implements the
1019 * <code>Clob</code> interface can not be constructed, this method is
1020 * called on a closed connection or a database access error occurs.
1021 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1022 * this data type
1023 *
1024 * @since 1.6
1025 */
1026 Clob createClob() throws SQLException;
1027
1028 /**
1029 * Constructs an object that implements the <code>Blob</code> interface. The object
1030 * returned initially contains no data. The <code>setBinaryStream</code> and
1031 * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to
1032 * the <code>Blob</code>.
1033 * @return An object that implements the <code>Blob</code> interface
1034 * @throws SQLException if an object that implements the
1035 * <code>Blob</code> interface can not be constructed, this method is
1036 * called on a closed connection or a database access error occurs.
1037 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1038 * this data type
1039 *
1040 * @since 1.6
1041 */
1042 Blob createBlob() throws SQLException;
1043
1044 /**
1045 * Constructs an object that implements the <code>NClob</code> interface. The object
1046 * returned initially contains no data. The <code>setAsciiStream</code>,
1047 * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may
1048 * be used to add data to the <code>NClob</code>.
1049 * @return An object that implements the <code>NClob</code> interface
1050 * @throws SQLException if an object that implements the
1051 * <code>NClob</code> interface can not be constructed, this method is
1052 * called on a closed connection or a database access error occurs.
1053 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1054 * this data type
1055 *
1056 * @since 1.6
1057 */
1058 NClob createNClob() throws SQLException;
1059
1060 /**
1061 * Constructs an object that implements the <code>SQLXML</code> interface. The object
1062 * returned initially contains no data. The <code>createXmlStreamWriter</code> object and
1063 * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code>
1064 * object.
1065 * @return An object that implements the <code>SQLXML</code> interface
1066 * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not
1067 * be constructed, this method is
1068 * called on a closed connection or a database access error occurs.
1069 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1070 * this data type
1071 * @since 1.6
1072 */
1073 SQLXML createSQLXML() throws SQLException;
1074
1075 /**
1076 * Returns true if the connection has not been closed and is still valid.
1077 * The driver shall submit a query on the connection or use some other
1078 * mechanism that positively verifies the connection is still valid when
1079 * this method is called.
1080 * <p>
1081 * The query submitted by the driver to validate the connection shall be
1082 * executed in the context of the current transaction.
1083 *
1084 * @param timeout - The time in seconds to wait for the database operation
1085 * used to validate the connection to complete. If
1086 * the timeout period expires before the operation
1087 * completes, this method returns false. A value of
1088 * 0 indicates a timeout is not applied to the
1089 * database operation.
1090 * <p>
1091 * @return true if the connection is valid, false otherwise
1092 * @exception SQLException if the value supplied for <code>timeout</code>
1093 * is less then 0
1094 * @since 1.6
1095 * <p>
1096 * @see java.sql.DatabaseMetaData#getClientInfoProperties
1097 */
1098 boolean isValid(int timeout) throws SQLException;
1099
1100 /**
1101 * Sets the value of the client info property specified by name to the
1102 * value specified by value.
1103 * <p>
1104 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1105 * method to determine the client info properties supported by the driver
1106 * and the maximum length that may be specified for each property.
1107 * <p>
1108 * The driver stores the value specified in a suitable location in the
1109 * database. For example in a special register, session parameter, or
1110 * system table column. For efficiency the driver may defer setting the
1111 * value in the database until the next time a statement is executed or
1112 * prepared. Other than storing the client information in the appropriate
1113 * place in the database, these methods shall not alter the behavior of
1114 * the connection in anyway. The values supplied to these methods are
1115 * used for accounting, diagnostics and debugging purposes only.
1116 * <p>
1117 * The driver shall generate a warning if the client info name specified
1118 * is not recognized by the driver.
1119 * <p>
1120 * If the value specified to this method is greater than the maximum
1121 * length for the property the driver may either truncate the value and
1122 * generate a warning or generate a <code>SQLClientInfoException</code>. If the driver
1123 * generates a <code>SQLClientInfoException</code>, the value specified was not set on the
1124 * connection.
1125 * <p>
1126 * The following are standard client info properties. Drivers are not
1127 * required to support these properties however if the driver supports a
1128 * client info property that can be described by one of the standard
1129 * properties, the standard property name should be used.
1130 * <p>
1131 * <ul>
1132 * <li>ApplicationName - The name of the application currently utilizing
1133 * the connection</li>
1134 * <li>ClientUser - The name of the user that the application using
1135 * the connection is performing work for. This may
1136 * not be the same as the user name that was used
1137 * in establishing the connection.</li>
1138 * <li>ClientHostname - The hostname of the computer the application
1139 * using the connection is running on.</li>
1140 * </ul>
1141 * <p>
1142 * @param name The name of the client info property to set
1143 * @param value The value to set the client info property to. If the
1144 * value is null, the current value of the specified
1145 * property is cleared.
1146 * <p>
1147 * @throws SQLClientInfoException if the database server returns an error while
1148 * setting the client info value on the database server or this method
1149 * is called on a closed connection
1150 * <p>
1151 * @since 1.6
1152 */
1153 void setClientInfo(String name, String value)
1154 throws SQLClientInfoException;
1155
1156 /**
1157 * Sets the value of the connection's client info properties. The
1158 * <code>Properties</code> object contains the names and values of the client info
1159 * properties to be set. The set of client info properties contained in
1160 * the properties list replaces the current set of client info properties
1161 * on the connection. If a property that is currently set on the
1162 * connection is not present in the properties list, that property is
1163 * cleared. Specifying an empty properties list will clear all of the
1164 * properties on the connection. See <code>setClientInfo (String, String)</code> for
1165 * more information.
1166 * <p>
1167 * If an error occurs in setting any of the client info properties, a
1168 * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code>
1169 * contains information indicating which client info properties were not set.
1170 * The state of the client information is unknown because
1171 * some databases do not allow multiple client info properties to be set
1172 * atomically. For those databases, one or more properties may have been
1173 * set before the error occurred.
1174 * <p>
1175 *
1176 * @param properties the list of client info properties to set
1177 * <p>
1178 * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String)
1179 * @since 1.6
1180 * <p>
1181 * @throws SQLClientInfoException if the database server returns an error while
1182 * setting the clientInfo values on the database server or this method
1183 * is called on a closed connection
1184 * <p>
1185 */
1186 void setClientInfo(Properties properties)
1187 throws SQLClientInfoException;
1188
1189 /**
1190 * Returns the value of the client info property specified by name. This
1191 * method may return null if the specified client info property has not
1192 * been set and does not have a default value. This method will also
1193 * return null if the specified client info property name is not supported
1194 * by the driver.
1195 * <p>
1196 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1197 * method to determine the client info properties supported by the driver.
1198 * <p>
1199 * @param name The name of the client info property to retrieve
1200 * <p>
1201 * @return The value of the client info property specified
1202 * <p>
1203 * @throws SQLException if the database server returns an error when
1204 * fetching the client info value from the database
1205 *or this method is called on a closed connection
1206 * <p>
1207 * @since 1.6
1208 * <p>
1209 * @see java.sql.DatabaseMetaData#getClientInfoProperties
1210 */
1211 String getClientInfo(String name)
1212 throws SQLException;
1213
1214 /**
1215 * Returns a list containing the name and current value of each client info
1216 * property supported by the driver. The value of a client info property
1217 * may be null if the property has not been set and does not have a
1218 * default value.
1219 * <p>
1220 * @return A <code>Properties</code> object that contains the name and current value of
1221 * each of the client info properties supported by the driver.
1222 * <p>
1223 * @throws SQLException if the database server returns an error when
1224 * fetching the client info values from the database
1225 * or this method is called on a closed connection
1226 * <p>
1227 * @since 1.6
1228 */
1229 Properties getClientInfo()
1230 throws SQLException;
1231
1232 /**
1233 * Factory method for creating Array objects.
1234 *<p>
1235 * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object
1236 * that maps to a primitive data type, then it is implementation-defined
1237 * whether the <code>Array</code> object is an array of that primitive
1238 * data type or an array of <code>Object</code>.
1239 * <p>
1240 * <b>Note: </b>The JDBC driver is responsible for mapping the elements
1241 * <code>Object</code> array to the default JDBC SQL type defined in
1242 * java.sql.Types for the given class of <code>Object</code>. The default
1243 * mapping is specified in Appendix B of the JDBC specification. If the
1244 * resulting JDBC type is not the appropriate type for the given typeName then
1245 * it is implementation defined whether an <code>SQLException</code> is
1246 * thrown or the driver supports the resulting conversion.
1247 *
1248 * @param typeName the SQL name of the type the elements of the array map to. The typeName is a
1249 * 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
1250 * is the value returned by <code>Array.getBaseTypeName</code>
1251 * @param elements the elements that populate the returned object
1252 * @return an Array object whose elements map to the specified SQL type
1253 * @throws SQLException if a database error occurs, the JDBC type is not
1254 * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection
1255 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type
1256 * @since 1.6
1257 */
1258 Array createArrayOf(String typeName, Object[] elements) throws
1259 SQLException;
1260
1261 /**
1262 * Factory method for creating Struct objects.
1263 *
1264 * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code>
1265 * object maps to. The typeName is the name of a user-defined type that
1266 * has been defined for this database. It is the value returned by
1267 * <code>Struct.getSQLTypeName</code>.
1268
1269 * @param attributes the attributes that populate the returned object
1270 * @return a Struct object that maps to the given SQL type and is populated with the given attributes
1271 * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection
1272 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type
1273 * @since 1.6
1274 */
1275 Struct createStruct(String typeName, Object[] attributes)
1276 throws SQLException;
1277 }
Save This Page