View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, 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      * <P>
277      *
278      * @exception SQLException SQLException if a database access error occurs
279      */
280     void close() throws SQLException;
281 
282     /**
283      * Retrieves whether this <code>Connection</code> object has been
284      * closed.  A connection is closed if the method <code>close</code>
285      * has been called on it or if certain fatal errors have occurred.
286      * This method is guaranteed to return <code>true</code> only when
287      * it is called after the method <code>Connection.close</code> has
288      * been called.
289      * <P>
290      * This method generally cannot be called to determine whether a
291      * connection to a database is valid or invalid.  A typical client
292      * can determine that a connection is invalid by catching any
293      * exceptions that might be thrown when an operation is attempted.
294      *
295      * @return <code>true</code> if this <code>Connection</code> object
296      *         is closed; <code>false</code> if it is still open
297      * @exception SQLException if a database access error occurs
298      */
299     boolean isClosed() throws SQLException;
300 
301     //======================================================================
302     // Advanced features:
303 
304     /**
305      * Retrieves a <code>DatabaseMetaData</code> object that contains
306      * metadata about the database to which this
307      * <code>Connection</code> object represents a connection.
308      * The metadata includes information about the database's
309      * tables, its supported SQL grammar, its stored
310      * procedures, the capabilities of this connection, and so on.
311      *
312      * @return a <code>DatabaseMetaData</code> object for this
313      *         <code>Connection</code> object
314      * @exception  SQLException if a database access error occurs
315      * or this method is called on a closed connection
316      */
317     DatabaseMetaData getMetaData() throws SQLException;
318 
319     /**
320      * Puts this connection in read-only mode as a hint to the driver to enable
321      * database optimizations.
322      *
323      * <P><B>Note:</B> This method cannot be called during a transaction.
324      *
325      * @param readOnly <code>true</code> enables read-only mode;
326      *        <code>false</code> disables it
327      * @exception SQLException if a database access error occurs, this
328      *  method is called on a closed connection or this
329      *            method is called during a transaction
330      */
331     void setReadOnly(boolean readOnly) throws SQLException;
332 
333     /**
334      * Retrieves whether this <code>Connection</code>
335      * object is in read-only mode.
336      *
337      * @return <code>true</code> if this <code>Connection</code> object
338      *         is read-only; <code>false</code> otherwise
339      * @exception SQLException SQLException if a database access error occurs
340      * or this method is called on a closed connection
341      */
342     boolean isReadOnly() throws SQLException;
343 
344     /**
345      * Sets the given catalog name in order to select
346      * a subspace of this <code>Connection</code> object's database
347      * in which to work.
348      * <P>
349      * If the driver does not support catalogs, it will
350      * silently ignore this request.
351      * <p>
352      * Calling {@code setCatalog} has no effect on previously created or prepared
353      * {@code Statement} objects. It is implementation defined whether a DBMS
354      * prepare operation takes place immediately when the {@code Connection}
355      * method {@code prepareStatement} or {@code prepareCall} is invoked.
356      * For maximum portability, {@code setCatalog} should be called before a
357      * {@code Statement} is created or prepared.
358      *
359      * @param catalog the name of a catalog (subspace in this
360      *        <code>Connection</code> object's database) in which to work
361      * @exception SQLException if a database access error occurs
362      * or this method is called on a closed connection
363      * @see #getCatalog
364      */
365     void setCatalog(String catalog) throws SQLException;
366 
367     /**
368      * Retrieves this <code>Connection</code> object's current catalog name.
369      *
370      * @return the current catalog name or <code>null</code> if there is none
371      * @exception SQLException if a database access error occurs
372      * or this method is called on a closed connection
373      * @see #setCatalog
374      */
375     String getCatalog() throws SQLException;
376 
377     /**
378      * A constant indicating that transactions are not supported.
379      */
380     int TRANSACTION_NONE             = 0;
381 
382     /**
383      * A constant indicating that
384      * dirty reads, non-repeatable reads and phantom reads can occur.
385      * This level allows a row changed by one transaction to be read
386      * by another transaction before any changes in that row have been
387      * committed (a "dirty read").  If any of the changes are rolled back,
388      * the second transaction will have retrieved an invalid row.
389      */
390     int TRANSACTION_READ_UNCOMMITTED = 1;
391 
392     /**
393      * A constant indicating that
394      * dirty reads are prevented; non-repeatable reads and phantom
395      * reads can occur.  This level only prohibits a transaction
396      * from reading a row with uncommitted changes in it.
397      */
398     int TRANSACTION_READ_COMMITTED   = 2;
399 
400     /**
401      * A constant indicating that
402      * dirty reads and non-repeatable reads are prevented; phantom
403      * reads can occur.  This level prohibits a transaction from
404      * reading a row with uncommitted changes in it, and it also
405      * prohibits the situation where one transaction reads a row,
406      * a second transaction alters the row, and the first transaction
407      * rereads the row, getting different values the second time
408      * (a "non-repeatable read").
409      */
410     int TRANSACTION_REPEATABLE_READ  = 4;
411 
412     /**
413      * A constant indicating that
414      * dirty reads, non-repeatable reads and phantom reads are prevented.
415      * This level includes the prohibitions in
416      * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the
417      * situation where one transaction reads all rows that satisfy
418      * a <code>WHERE</code> condition, a second transaction inserts a row that
419      * satisfies that <code>WHERE</code> condition, and the first transaction
420      * rereads for the same condition, retrieving the additional
421      * "phantom" row in the second read.
422      */
423     int TRANSACTION_SERIALIZABLE     = 8;
424 
425     /**
426      * Attempts to change the transaction isolation level for this
427      * <code>Connection</code> object to the one given.
428      * The constants defined in the interface <code>Connection</code>
429      * are the possible transaction isolation levels.
430      * <P>
431      * <B>Note:</B> If this method is called during a transaction, the result
432      * is implementation-defined.
433      *
434      * @param level one of the following <code>Connection</code> constants:
435      *        <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
436      *        <code>Connection.TRANSACTION_READ_COMMITTED</code>,
437      *        <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
438      *        <code>Connection.TRANSACTION_SERIALIZABLE</code>.
439      *        (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used
440      *        because it specifies that transactions are not supported.)
441      * @exception SQLException if a database access error occurs, this
442      * method is called on a closed connection
443      *            or the given parameter is not one of the <code>Connection</code>
444      *            constants
445      * @see DatabaseMetaData#supportsTransactionIsolationLevel
446      * @see #getTransactionIsolation
447      */
448     void setTransactionIsolation(int level) throws SQLException;
449 
450     /**
451      * Retrieves this <code>Connection</code> object's current
452      * transaction isolation level.
453      *
454      * @return the current transaction isolation level, which will be one
455      *         of the following constants:
456      *        <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
457      *        <code>Connection.TRANSACTION_READ_COMMITTED</code>,
458      *        <code>Connection.TRANSACTION_REPEATABLE_READ</code>,
459      *        <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
460      *        <code>Connection.TRANSACTION_NONE</code>.
461      * @exception SQLException if a database access error occurs
462      * or this method is called on a closed connection
463      * @see #setTransactionIsolation
464      */
465     int getTransactionIsolation() throws SQLException;
466 
467     /**
468      * Retrieves the first warning reported by calls on this
469      * <code>Connection</code> object.  If there is more than one
470      * warning, subsequent warnings will be chained to the first one
471      * and can be retrieved by calling the method
472      * <code>SQLWarning.getNextWarning</code> on the warning
473      * that was retrieved previously.
474      * <P>
475      * This method may not be
476      * called on a closed connection; doing so will cause an
477      * <code>SQLException</code> to be thrown.
478      *
479      * <P><B>Note:</B> Subsequent warnings will be chained to this
480      * SQLWarning.
481      *
482      * @return the first <code>SQLWarning</code> object or <code>null</code>
483      *         if there are none
484      * @exception SQLException if a database access error occurs or
485      *            this method is called on a closed connection
486      * @see SQLWarning
487      */
488     SQLWarning getWarnings() throws SQLException;
489 
490     /**
491      * Clears all warnings reported for this <code>Connection</code> object.
492      * After a call to this method, the method <code>getWarnings</code>
493      * returns <code>null</code> until a new warning is
494      * reported for this <code>Connection</code> object.
495      *
496      * @exception SQLException SQLException if a database access error occurs
497      * or this method is called on a closed connection
498      */
499     void clearWarnings() throws SQLException;
500 
501 
502     //--------------------------JDBC 2.0-----------------------------
503 
504     /**
505      * Creates a <code>Statement</code> object that will generate
506      * <code>ResultSet</code> objects with the given type and concurrency.
507      * This method is the same as the <code>createStatement</code> method
508      * above, but it allows the default result set
509      * type and concurrency to be overridden.
510      * The holdability of the created result sets can be determined by
511      * calling {@link #getHoldability}.
512      *
513      * @param resultSetType a result set type; one of
514      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
515      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
516      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
517      * @param resultSetConcurrency a concurrency type; one of
518      *        <code>ResultSet.CONCUR_READ_ONLY</code> or
519      *        <code>ResultSet.CONCUR_UPDATABLE</code>
520      * @return a new <code>Statement</code> object that will generate
521      *         <code>ResultSet</code> objects with the given type and
522      *         concurrency
523      * @exception SQLException if a database access error occurs, this
524      * method is called on a closed connection
525      *         or the given parameters are not <code>ResultSet</code>
526      *         constants indicating type and concurrency
527      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
528      * this method or this method is not supported for the specified result
529      * set type and result set concurrency.
530      * @since 1.2
531      */
532     Statement createStatement(int resultSetType, int resultSetConcurrency)
533         throws SQLException;
534 
535     /**
536      *
537      * Creates a <code>PreparedStatement</code> object that will generate
538      * <code>ResultSet</code> objects with the given type and concurrency.
539      * This method is the same as the <code>prepareStatement</code> method
540      * above, but it allows the default result set
541      * type and concurrency to be overridden.
542      * The holdability of the created result sets can be determined by
543      * calling {@link #getHoldability}.
544      *
545      * @param sql a <code>String</code> object that is the SQL statement to
546      *            be sent to the database; may contain one or more '?' IN
547      *            parameters
548      * @param resultSetType a result set type; one of
549      *         <code>ResultSet.TYPE_FORWARD_ONLY</code>,
550      *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
551      *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
552      * @param resultSetConcurrency a concurrency type; one of
553      *         <code>ResultSet.CONCUR_READ_ONLY</code> or
554      *         <code>ResultSet.CONCUR_UPDATABLE</code>
555      * @return a new PreparedStatement object containing the
556      * pre-compiled SQL statement that will produce <code>ResultSet</code>
557      * objects with the given type and concurrency
558      * @exception SQLException if a database access error occurs, this
559      * method is called on a closed connection
560      *         or the given parameters are not <code>ResultSet</code>
561      *         constants indicating type and concurrency
562      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
563      * this method or this method is not supported for the specified result
564      * set type and result set concurrency.
565      * @since 1.2
566      */
567     PreparedStatement prepareStatement(String sql, int resultSetType,
568                                        int resultSetConcurrency)
569         throws SQLException;
570 
571     /**
572      * Creates a <code>CallableStatement</code> object that will generate
573      * <code>ResultSet</code> objects with the given type and concurrency.
574      * This method is the same as the <code>prepareCall</code> method
575      * above, but it allows the default result set
576      * type and concurrency to be overridden.
577      * The holdability of the created result sets can be determined by
578      * calling {@link #getHoldability}.
579      *
580      * @param sql a <code>String</code> object that is the SQL statement to
581      *            be sent to the database; may contain on or more '?' parameters
582      * @param resultSetType a result set type; one of
583      *         <code>ResultSet.TYPE_FORWARD_ONLY</code>,
584      *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
585      *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
586      * @param resultSetConcurrency a concurrency type; one of
587      *         <code>ResultSet.CONCUR_READ_ONLY</code> or
588      *         <code>ResultSet.CONCUR_UPDATABLE</code>
589      * @return a new <code>CallableStatement</code> object containing the
590      * pre-compiled SQL statement that will produce <code>ResultSet</code>
591      * objects with the given type and concurrency
592      * @exception SQLException if a database access error occurs, this method
593      * is called on a closed connection
594      *         or the given parameters are not <code>ResultSet</code>
595      *         constants indicating type and concurrency
596      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
597      * this method or this method is not supported for the specified result
598      * set type and result set concurrency.
599      * @since 1.2
600      */
601     CallableStatement prepareCall(String sql, int resultSetType,
602                                   int resultSetConcurrency) throws SQLException;
603 
604     /**
605      * Retrieves the <code>Map</code> object associated with this
606      * <code>Connection</code> object.
607      * Unless the application has added an entry, the type map returned
608      * will be empty.
609      * <p>
610      * You must invoke <code>setTypeMap</code> after making changes to the
611      * <code>Map</code> object returned from
612      *  <code>getTypeMap</code> as a JDBC driver may create an internal
613      * copy of the <code>Map</code> object passed to <code>setTypeMap</code>:
614      *
615      * <pre>
616      *      Map&lt;String,Class&lt;?&gt;&gt; myMap = con.getTypeMap();
617      *      myMap.put("mySchemaName.ATHLETES", Athletes.class);
618      *      con.setTypeMap(myMap);
619      * </pre>
620      * @return the <code>java.util.Map</code> object associated
621      *         with this <code>Connection</code> object
622      * @exception SQLException if a database access error occurs
623      * or this method is called on a closed connection
624      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
625      * this method
626      * @since 1.2
627      * @see #setTypeMap
628      */
629     java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
630 
631     /**
632      * Installs the given <code>TypeMap</code> object as the type map for
633      * this <code>Connection</code> object.  The type map will be used for the
634      * custom mapping of SQL structured types and distinct types.
635      *<p>
636      * You must set the the values for the <code>TypeMap</code> prior to
637      * callng <code>setMap</code> as a JDBC driver may create an internal copy
638      * of the <code>TypeMap</code>:
639      *
640      * <pre>
641      *      Map myMap&lt;String,Class&lt;?&gt;&gt; = new HashMap&lt;String,Class&lt;?&gt;&gt;();
642      *      myMap.put("mySchemaName.ATHLETES", Athletes.class);
643      *      con.setTypeMap(myMap);
644      * </pre>
645      * @param map the <code>java.util.Map</code> object to install
646      *        as the replacement for this <code>Connection</code>
647      *        object's default type map
648      * @exception SQLException if a database access error occurs, this
649      * method is called on a closed connection or
650      *        the given parameter is not a <code>java.util.Map</code>
651      *        object
652      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
653      * this method
654      * @since 1.2
655      * @see #getTypeMap
656      */
657     void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
658 
659     //--------------------------JDBC 3.0-----------------------------
660 
661 
662     /**
663      * Changes the default holdability of <code>ResultSet</code> objects
664      * created using this <code>Connection</code> object to the given
665      * holdability.  The default holdability of <code>ResultSet</code> objects
666      * can be be determined by invoking
667      * {@link DatabaseMetaData#getResultSetHoldability}.
668      *
669      * @param holdability a <code>ResultSet</code> holdability constant; one of
670      *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
671      *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
672      * @throws SQLException if a database access occurs, this method is called
673      * on a closed connection, or the given parameter
674      *         is not a <code>ResultSet</code> constant indicating holdability
675      * @exception SQLFeatureNotSupportedException if the given holdability is not supported
676      * @see #getHoldability
677      * @see DatabaseMetaData#getResultSetHoldability
678      * @see ResultSet
679      * @since 1.4
680      */
681     void setHoldability(int holdability) throws SQLException;
682 
683     /**
684      * Retrieves the current holdability of <code>ResultSet</code> objects
685      * created using this <code>Connection</code> object.
686      *
687      * @return the holdability, one of
688      *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
689      *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
690      * @throws SQLException if a database access error occurs
691      * or this method is called on a closed connection
692      * @see #setHoldability
693      * @see DatabaseMetaData#getResultSetHoldability
694      * @see ResultSet
695      * @since 1.4
696      */
697     int getHoldability() throws SQLException;
698 
699     /**
700      * Creates an unnamed savepoint in the current transaction and
701      * returns the new <code>Savepoint</code> object that represents it.
702      *
703      *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
704      *savepoint.
705      *
706      * @return the new <code>Savepoint</code> object
707      * @exception SQLException if a database access error occurs,
708      * this method is called while participating in a distributed transaction,
709      * this method is called on a closed connection
710      *            or this <code>Connection</code> object is currently in
711      *            auto-commit mode
712      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
713      * this method
714      * @see Savepoint
715      * @since 1.4
716      */
717     Savepoint setSavepoint() throws SQLException;
718 
719     /**
720      * Creates a savepoint with the given name in the current transaction
721      * and returns the new <code>Savepoint</code> object that represents it.
722      *
723      * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
724      *savepoint.
725      *
726      * @param name a <code>String</code> containing the name of the savepoint
727      * @return the new <code>Savepoint</code> object
728      * @exception SQLException if a database access error occurs,
729           * this method is called while participating in a distributed transaction,
730      * this method is called on a closed connection
731      *            or this <code>Connection</code> object is currently in
732      *            auto-commit mode
733      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
734      * this method
735      * @see Savepoint
736      * @since 1.4
737      */
738     Savepoint setSavepoint(String name) throws SQLException;
739 
740     /**
741      * Undoes all changes made after the given <code>Savepoint</code> object
742      * was set.
743      * <P>
744      * This method should be used only when auto-commit has been disabled.
745      *
746      * @param savepoint the <code>Savepoint</code> object to roll back to
747      * @exception SQLException if a database access error occurs,
748      * this method is called while participating in a distributed transaction,
749      * this method is called on a closed connection,
750      *            the <code>Savepoint</code> object is no longer valid,
751      *            or this <code>Connection</code> object is currently in
752      *            auto-commit mode
753      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
754      * this method
755      * @see Savepoint
756      * @see #rollback
757      * @since 1.4
758      */
759     void rollback(Savepoint savepoint) throws SQLException;
760 
761     /**
762      * Removes the specified <code>Savepoint</code>  and subsequent <code>Savepoint</code> objects from the current
763      * transaction. Any reference to the savepoint after it have been removed
764      * will cause an <code>SQLException</code> to be thrown.
765      *
766      * @param savepoint the <code>Savepoint</code> object to be removed
767      * @exception SQLException if a database access error occurs, this
768      *  method is called on a closed connection or
769      *            the given <code>Savepoint</code> object is not a valid
770      *            savepoint in the current transaction
771      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
772      * this method
773      * @since 1.4
774      */
775     void releaseSavepoint(Savepoint savepoint) throws SQLException;
776 
777     /**
778      * Creates a <code>Statement</code> object that will generate
779      * <code>ResultSet</code> objects with the given type, concurrency,
780      * and holdability.
781      * This method is the same as the <code>createStatement</code> method
782      * above, but it allows the default result set
783      * type, concurrency, and holdability to be overridden.
784      *
785      * @param resultSetType one of the following <code>ResultSet</code>
786      *        constants:
787      *         <code>ResultSet.TYPE_FORWARD_ONLY</code>,
788      *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
789      *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
790      * @param resultSetConcurrency one of the following <code>ResultSet</code>
791      *        constants:
792      *         <code>ResultSet.CONCUR_READ_ONLY</code> or
793      *         <code>ResultSet.CONCUR_UPDATABLE</code>
794      * @param resultSetHoldability one of the following <code>ResultSet</code>
795      *        constants:
796      *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
797      *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
798      * @return a new <code>Statement</code> object that will generate
799      *         <code>ResultSet</code> objects with the given type,
800      *         concurrency, and holdability
801      * @exception SQLException if a database access error occurs, this
802      * method is called on a closed connection
803      *            or the given parameters are not <code>ResultSet</code>
804      *            constants indicating type, concurrency, and holdability
805      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
806      * this method or this method is not supported for the specified result
807      * set type, result set holdability and result set concurrency.
808      * @see ResultSet
809      * @since 1.4
810      */
811     Statement createStatement(int resultSetType, int resultSetConcurrency,
812                               int resultSetHoldability) throws SQLException;
813 
814     /**
815      * Creates a <code>PreparedStatement</code> object that will generate
816      * <code>ResultSet</code> objects with the given type, concurrency,
817      * and holdability.
818      * <P>
819      * This method is the same as the <code>prepareStatement</code> method
820      * above, but it allows the default result set
821      * type, concurrency, and holdability to be overridden.
822      *
823      * @param sql a <code>String</code> object that is the SQL statement to
824      *            be sent to the database; may contain one or more '?' IN
825      *            parameters
826      * @param resultSetType one of the following <code>ResultSet</code>
827      *        constants:
828      *         <code>ResultSet.TYPE_FORWARD_ONLY</code>,
829      *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
830      *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
831      * @param resultSetConcurrency one of the following <code>ResultSet</code>
832      *        constants:
833      *         <code>ResultSet.CONCUR_READ_ONLY</code> or
834      *         <code>ResultSet.CONCUR_UPDATABLE</code>
835      * @param resultSetHoldability one of the following <code>ResultSet</code>
836      *        constants:
837      *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
838      *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
839      * @return a new <code>PreparedStatement</code> object, containing the
840      *         pre-compiled SQL statement, that will generate
841      *         <code>ResultSet</code> objects with the given type,
842      *         concurrency, and holdability
843      * @exception SQLException if a database access error occurs, this
844      * method is called on a closed connection
845      *            or the given parameters are not <code>ResultSet</code>
846      *            constants indicating type, concurrency, and holdability
847       * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
848      * this method or this method is not supported for the specified result
849      * set type, result set holdability and result set concurrency.
850      * @see ResultSet
851      * @since 1.4
852      */
853     PreparedStatement prepareStatement(String sql, int resultSetType,
854                                        int resultSetConcurrency, int resultSetHoldability)
855         throws SQLException;
856 
857     /**
858      * Creates a <code>CallableStatement</code> object that will generate
859      * <code>ResultSet</code> objects with the given type and concurrency.
860      * This method is the same as the <code>prepareCall</code> method
861      * above, but it allows the default result set
862      * type, result set concurrency type and holdability to be overridden.
863      *
864      * @param sql a <code>String</code> object that is the SQL statement to
865      *            be sent to the database; may contain on or more '?' parameters
866      * @param resultSetType one of the following <code>ResultSet</code>
867      *        constants:
868      *         <code>ResultSet.TYPE_FORWARD_ONLY</code>,
869      *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
870      *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
871      * @param resultSetConcurrency one of the following <code>ResultSet</code>
872      *        constants:
873      *         <code>ResultSet.CONCUR_READ_ONLY</code> or
874      *         <code>ResultSet.CONCUR_UPDATABLE</code>
875      * @param resultSetHoldability one of the following <code>ResultSet</code>
876      *        constants:
877      *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
878      *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
879      * @return a new <code>CallableStatement</code> object, containing the
880      *         pre-compiled SQL statement, that will generate
881      *         <code>ResultSet</code> objects with the given type,
882      *         concurrency, and holdability
883      * @exception SQLException if a database access error occurs, this
884      * method is called on a closed connection
885      *            or the given parameters are not <code>ResultSet</code>
886      *            constants indicating type, concurrency, and holdability
887       * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
888      * this method or this method is not supported for the specified result
889      * set type, result set holdability and result set concurrency.
890      * @see ResultSet
891      * @since 1.4
892      */
893     CallableStatement prepareCall(String sql, int resultSetType,
894                                   int resultSetConcurrency,
895                                   int resultSetHoldability) throws SQLException;
896 
897 
898     /**
899      * Creates a default <code>PreparedStatement</code> object that has
900      * the capability to retrieve auto-generated keys. The given constant
901      * tells the driver whether it should make auto-generated keys
902      * available for retrieval.  This parameter is ignored if the SQL statement
903      * is not an <code>INSERT</code> statement, or an SQL statement able to return
904      * auto-generated keys (the list of such statements is vendor-specific).
905      * <P>
906      * <B>Note:</B> This method is optimized for handling
907      * parametric SQL statements that benefit from precompilation. If
908      * the driver supports precompilation,
909      * the method <code>prepareStatement</code> will send
910      * the statement to the database for precompilation. Some drivers
911      * may not support precompilation. In this case, the statement may
912      * not be sent to the database until the <code>PreparedStatement</code>
913      * object is executed.  This has no direct effect on users; however, it does
914      * affect which methods throw certain SQLExceptions.
915      * <P>
916      * Result sets created using the returned <code>PreparedStatement</code>
917      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
918      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
919      * The holdability of the created result sets can be determined by
920      * calling {@link #getHoldability}.
921      *
922      * @param sql an SQL statement that may contain one or more '?' IN
923      *        parameter placeholders
924      * @param autoGeneratedKeys a flag indicating whether auto-generated keys
925      *        should be returned; one of
926      *        <code>Statement.RETURN_GENERATED_KEYS</code> or
927      *        <code>Statement.NO_GENERATED_KEYS</code>
928      * @return a new <code>PreparedStatement</code> object, containing the
929      *         pre-compiled SQL statement, that will have the capability of
930      *         returning auto-generated keys
931      * @exception SQLException if a database access error occurs, this
932      *  method is called on a closed connection
933      *         or the given parameter is not a <code>Statement</code>
934      *         constant indicating whether auto-generated keys should be
935      *         returned
936      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
937      * this method with a constant of Statement.RETURN_GENERATED_KEYS
938      * @since 1.4
939      */
940     PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
941         throws SQLException;
942 
943     /**
944      * Creates a default <code>PreparedStatement</code> object capable
945      * of returning the auto-generated keys designated by the given array.
946      * This array contains the indexes of the columns in the target
947      * table that contain the auto-generated keys that should be made
948      * available.  The driver will ignore the array if the SQL statement
949      * is not an <code>INSERT</code> statement, or an SQL statement able to return
950      * auto-generated keys (the list of such statements is vendor-specific).
951      *<p>
952      * An SQL statement with or without IN parameters can be
953      * pre-compiled and stored in a <code>PreparedStatement</code> object. This
954      * object can then be used to efficiently execute this statement
955      * multiple times.
956      * <P>
957      * <B>Note:</B> This method is optimized for handling
958      * parametric SQL statements that benefit from precompilation. If
959      * the driver supports precompilation,
960      * the method <code>prepareStatement</code> will send
961      * the statement to the database for precompilation. Some drivers
962      * may not support precompilation. In this case, the statement may
963      * not be sent to the database until the <code>PreparedStatement</code>
964      * object is executed.  This has no direct effect on users; however, it does
965      * affect which methods throw certain SQLExceptions.
966      * <P>
967      * Result sets created using the returned <code>PreparedStatement</code>
968      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
969      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
970      * The holdability of the created result sets can be determined by
971      * calling {@link #getHoldability}.
972      *
973      * @param sql an SQL statement that may contain one or more '?' IN
974      *        parameter placeholders
975      * @param columnIndexes an array of column indexes indicating the columns
976      *        that should be returned from the inserted row or rows
977      * @return a new <code>PreparedStatement</code> object, containing the
978      *         pre-compiled statement, that is capable of returning the
979      *         auto-generated keys designated by the given array of column
980      *         indexes
981      * @exception SQLException if a database access error occurs
982      * or this method is called on a closed connection
983      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
984      * this method
985      *
986      * @since 1.4
987      */
988     PreparedStatement prepareStatement(String sql, int columnIndexes[])
989         throws SQLException;
990 
991     /**
992      * Creates a default <code>PreparedStatement</code> object capable
993      * of returning the auto-generated keys designated by the given array.
994      * This array contains the names of the columns in the target
995      * table that contain the auto-generated keys that should be returned.
996      * The driver will ignore the array if the SQL statement
997      * is not an <code>INSERT</code> statement, or an SQL statement able to return
998      * auto-generated keys (the list of such statements is vendor-specific).
999      * <P>
1000      * An SQL statement with or without IN parameters can be
1001      * pre-compiled and stored in a <code>PreparedStatement</code> object. This
1002      * object can then be used to efficiently execute this statement
1003      * multiple times.
1004      * <P>
1005      * <B>Note:</B> This method is optimized for handling
1006      * parametric SQL statements that benefit from precompilation. If
1007      * the driver supports precompilation,
1008      * the method <code>prepareStatement</code> will send
1009      * the statement to the database for precompilation. Some drivers
1010      * may not support precompilation. In this case, the statement may
1011      * not be sent to the database until the <code>PreparedStatement</code>
1012      * object is executed.  This has no direct effect on users; however, it does
1013      * affect which methods throw certain SQLExceptions.
1014      * <P>
1015      * Result sets created using the returned <code>PreparedStatement</code>
1016      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
1017      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
1018      * The holdability of the created result sets can be determined by
1019      * calling {@link #getHoldability}.
1020      *
1021      * @param sql an SQL statement that may contain one or more '?' IN
1022      *        parameter placeholders
1023      * @param columnNames an array of column names indicating the columns
1024      *        that should be returned from the inserted row or rows
1025      * @return a new <code>PreparedStatement</code> object, containing the
1026      *         pre-compiled statement, that is capable of returning the
1027      *         auto-generated keys designated by the given array of column
1028      *         names
1029      * @exception SQLException if a database access error occurs
1030      * or this method is called on a closed connection
1031      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1032      * this method
1033      *
1034      * @since 1.4
1035      */
1036     PreparedStatement prepareStatement(String sql, String columnNames[])
1037         throws SQLException;
1038 
1039     /**
1040      * Constructs an object that implements the <code>Clob</code> interface. The object
1041      * returned initially contains no data.  The <code>setAsciiStream</code>,
1042      * <code>setCharacterStream</code> and <code>setString</code> methods of
1043      * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>.
1044      * @return An object that implements the <code>Clob</code> interface
1045      * @throws SQLException if an object that implements the
1046      * <code>Clob</code> interface can not be constructed, this method is
1047      * called on a closed connection or a database access error occurs.
1048      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1049      * this data type
1050      *
1051      * @since 1.6
1052      */
1053     Clob createClob() throws SQLException;
1054 
1055     /**
1056      * Constructs an object that implements the <code>Blob</code> interface. The object
1057      * returned initially contains no data.  The <code>setBinaryStream</code> and
1058      * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to
1059      * the <code>Blob</code>.
1060      * @return  An object that implements the <code>Blob</code> interface
1061      * @throws SQLException if an object that implements the
1062      * <code>Blob</code> interface can not be constructed, this method is
1063      * called on a closed connection or a database access error occurs.
1064      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1065      * this data type
1066      *
1067      * @since 1.6
1068      */
1069     Blob createBlob() throws SQLException;
1070 
1071     /**
1072      * Constructs an object that implements the <code>NClob</code> interface. The object
1073      * returned initially contains no data.  The <code>setAsciiStream</code>,
1074      * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may
1075      * be used to add data to the <code>NClob</code>.
1076      * @return An object that implements the <code>NClob</code> interface
1077      * @throws SQLException if an object that implements the
1078      * <code>NClob</code> interface can not be constructed, this method is
1079      * called on a closed connection or a database access error occurs.
1080      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1081      * this data type
1082      *
1083      * @since 1.6
1084      */
1085     NClob createNClob() throws SQLException;
1086 
1087     /**
1088      * Constructs an object that implements the <code>SQLXML</code> interface. The object
1089      * returned initially contains no data. The <code>createXmlStreamWriter</code> object and
1090      * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code>
1091      * object.
1092      * @return An object that implements the <code>SQLXML</code> interface
1093      * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not
1094      * be constructed, this method is
1095      * called on a closed connection or a database access error occurs.
1096      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1097      * this data type
1098      * @since 1.6
1099      */
1100     SQLXML createSQLXML() throws SQLException;
1101 
1102         /**
1103          * Returns true if the connection has not been closed and is still valid.
1104          * The driver shall submit a query on the connection or use some other
1105          * mechanism that positively verifies the connection is still valid when
1106          * this method is called.
1107          * <p>
1108          * The query submitted by the driver to validate the connection shall be
1109          * executed in the context of the current transaction.
1110          *
1111          * @param timeout -             The time in seconds to wait for the database operation
1112          *                                              used to validate the connection to complete.  If
1113          *                                              the timeout period expires before the operation
1114          *                                              completes, this method returns false.  A value of
1115          *                                              0 indicates a timeout is not applied to the
1116          *                                              database operation.
1117          * <p>
1118          * @return true if the connection is valid, false otherwise
1119          * @exception SQLException if the value supplied for <code>timeout</code>
1120          * is less then 0
1121          * @since 1.6
1122          *
1123          * @see java.sql.DatabaseMetaData#getClientInfoProperties
1124          */
1125          boolean isValid(int timeout) throws SQLException;
1126 
1127         /**
1128          * Sets the value of the client info property specified by name to the
1129          * value specified by value.
1130          * <p>
1131          * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1132          * method to determine the client info properties supported by the driver
1133          * and the maximum length that may be specified for each property.
1134          * <p>
1135          * The driver stores the value specified in a suitable location in the
1136          * database.  For example in a special register, session parameter, or
1137          * system table column.  For efficiency the driver may defer setting the
1138          * value in the database until the next time a statement is executed or
1139          * prepared.  Other than storing the client information in the appropriate
1140          * place in the database, these methods shall not alter the behavior of
1141          * the connection in anyway.  The values supplied to these methods are
1142          * used for accounting, diagnostics and debugging purposes only.
1143          * <p>
1144          * The driver shall generate a warning if the client info name specified
1145          * is not recognized by the driver.
1146          * <p>
1147          * If the value specified to this method is greater than the maximum
1148          * length for the property the driver may either truncate the value and
1149          * generate a warning or generate a <code>SQLClientInfoException</code>.  If the driver
1150          * generates a <code>SQLClientInfoException</code>, the value specified was not set on the
1151          * connection.
1152          * <p>
1153          * The following are standard client info properties.  Drivers are not
1154          * required to support these properties however if the driver supports a
1155          * client info property that can be described by one of the standard
1156          * properties, the standard property name should be used.
1157          *
1158          * <ul>
1159          * <li>ApplicationName  -       The name of the application currently utilizing
1160          *                                                      the connection</li>
1161          * <li>ClientUser               -       The name of the user that the application using
1162          *                                                      the connection is performing work for.  This may
1163          *                                                      not be the same as the user name that was used
1164          *                                                      in establishing the connection.</li>
1165          * <li>ClientHostname   -       The hostname of the computer the application
1166          *                                                      using the connection is running on.</li>
1167          * </ul>
1168          * <p>
1169          * @param name          The name of the client info property to set
1170          * @param value         The value to set the client info property to.  If the
1171          *                                      value is null, the current value of the specified
1172          *                                      property is cleared.
1173          * <p>
1174          * @throws      SQLClientInfoException if the database server returns an error while
1175          *                      setting the client info value on the database server or this method
1176          * is called on a closed connection
1177          * <p>
1178          * @since 1.6
1179          */
1180          void setClientInfo(String name, String value)
1181                 throws SQLClientInfoException;
1182 
1183         /**
1184      * Sets the value of the connection's client info properties.  The
1185      * <code>Properties</code> object contains the names and values of the client info
1186      * properties to be set.  The set of client info properties contained in
1187      * the properties list replaces the current set of client info properties
1188      * on the connection.  If a property that is currently set on the
1189      * connection is not present in the properties list, that property is
1190      * cleared.  Specifying an empty properties list will clear all of the
1191      * properties on the connection.  See <code>setClientInfo (String, String)</code> for
1192      * more information.
1193      * <p>
1194      * If an error occurs in setting any of the client info properties, a
1195      * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code>
1196      * contains information indicating which client info properties were not set.
1197      * The state of the client information is unknown because
1198      * some databases do not allow multiple client info properties to be set
1199      * atomically.  For those databases, one or more properties may have been
1200      * set before the error occurred.
1201      * <p>
1202      *
1203      * @param properties                the list of client info properties to set
1204      * <p>
1205      * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String)
1206      * @since 1.6
1207      * <p>
1208      * @throws SQLClientInfoException if the database server returns an error while
1209      *                  setting the clientInfo values on the database server or this method
1210      * is called on a closed connection
1211      *
1212      */
1213          void setClientInfo(Properties properties)
1214                 throws SQLClientInfoException;
1215 
1216         /**
1217          * Returns the value of the client info property specified by name.  This
1218          * method may return null if the specified client info property has not
1219          * been set and does not have a default value.  This method will also
1220          * return null if the specified client info property name is not supported
1221          * by the driver.
1222          * <p>
1223          * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1224          * method to determine the client info properties supported by the driver.
1225          * <p>
1226          * @param name          The name of the client info property to retrieve
1227          * <p>
1228          * @return                      The value of the client info property specified
1229          * <p>
1230          * @throws SQLException         if the database server returns an error when
1231          *                                                      fetching the client info value from the database
1232          *or this method is called on a closed connection
1233          * <p>
1234          * @since 1.6
1235          *
1236          * @see java.sql.DatabaseMetaData#getClientInfoProperties
1237          */
1238          String getClientInfo(String name)
1239                 throws SQLException;
1240 
1241         /**
1242          * Returns a list containing the name and current value of each client info
1243          * property supported by the driver.  The value of a client info property
1244          * may be null if the property has not been set and does not have a
1245          * default value.
1246          * <p>
1247          * @return      A <code>Properties</code> object that contains the name and current value of
1248          *                      each of the client info properties supported by the driver.
1249          * <p>
1250          * @throws      SQLException if the database server returns an error when
1251          *                      fetching the client info values from the database
1252          * or this method is called on a closed connection
1253          * <p>
1254          * @since 1.6
1255          */
1256          Properties getClientInfo()
1257                 throws SQLException;
1258 
1259 /**
1260   * Factory method for creating Array objects.
1261   *<p>
1262   * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object
1263   * that maps to a primitive data type, then it is implementation-defined
1264   * whether the <code>Array</code> object is an array of that primitive
1265   * data type or an array of <code>Object</code>.
1266   * <p>
1267   * <b>Note: </b>The JDBC driver is responsible for mapping the elements
1268   * <code>Object</code> array to the default JDBC SQL type defined in
1269   * java.sql.Types for the given class of <code>Object</code>. The default
1270   * mapping is specified in Appendix B of the JDBC specification.  If the
1271   * resulting JDBC type is not the appropriate type for the given typeName then
1272   * it is implementation defined whether an <code>SQLException</code> is
1273   * thrown or the driver supports the resulting conversion.
1274   *
1275   * @param typeName the SQL name of the type the elements of the array map to. The typeName is a
1276   * 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
1277   *  is the value returned by <code>Array.getBaseTypeName</code>
1278   * @param elements the elements that populate the returned object
1279   * @return an Array object whose elements map to the specified SQL type
1280   * @throws SQLException if a database error occurs, the JDBC type is not
1281   *  appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection
1282   * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this data type
1283   * @since 1.6
1284   */
1285  Array createArrayOf(String typeName, Object[] elements) throws
1286 SQLException;
1287 
1288 /**
1289   * Factory method for creating Struct objects.
1290   *
1291   * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code>
1292   * object maps to. The typeName is the name of  a user-defined type that
1293   * has been defined for this database. It is the value returned by
1294   * <code>Struct.getSQLTypeName</code>.
1295 
1296   * @param attributes the attributes that populate the returned object
1297   *  @return a Struct object that maps to the given SQL type and is populated with the given attributes
1298   * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection
1299   * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this data type
1300   * @since 1.6
1301   */
1302  Struct createStruct(String typeName, Object[] attributes)
1303 throws SQLException;
1304 
1305    //--------------------------JDBC 4.1 -----------------------------
1306 
1307    /**
1308     * Sets the given schema name to access.
1309     * <P>
1310     * If the driver does not support schemas, it will
1311     * silently ignore this request.
1312     * <p>
1313     * Calling {@code setSchema} has no effect on previously created or prepared
1314     * {@code Statement} objects. It is implementation defined whether a DBMS
1315     * prepare operation takes place immediately when the {@code Connection}
1316     * method {@code prepareStatement} or {@code prepareCall} is invoked.
1317     * For maximum portability, {@code setSchema} should be called before a
1318     * {@code Statement} is created or prepared.
1319     *
1320     * @param schema the name of a schema  in which to work
1321     * @exception SQLException if a database access error occurs
1322     * or this method is called on a closed connection
1323     * @see #getSchema
1324     * @since 1.7
1325     */
1326     void setSchema(String schema) throws SQLException;
1327 
1328     /**
1329      * Retrieves this <code>Connection</code> object's current schema name.
1330      *
1331      * @return the current schema name or <code>null</code> if there is none
1332      * @exception SQLException if a database access error occurs
1333      * or this method is called on a closed connection
1334      * @see #setSchema
1335      * @since 1.7
1336      */
1337     String getSchema() throws SQLException;
1338 
1339     /**
1340      * Terminates an open connection.  Calling <code>abort</code> results in:
1341      * <ul>
1342      * <li>The connection marked as closed
1343      * <li>Closes any physical connection to the database
1344      * <li>Releases resources used by the connection
1345      * <li>Insures that any thread that is currently accessing the connection
1346      * will either progress to completion or throw an <code>SQLException</code>.
1347      * </ul>
1348      * <p>
1349      * Calling <code>abort</code> marks the connection closed and releases any
1350      * resources. Calling <code>abort</code> on a closed connection is a
1351      * no-op.
1352      * <p>
1353      * It is possible that the aborting and releasing of the resources that are
1354      * held by the connection can take an extended period of time.  When the
1355      * <code>abort</code> method returns, the connection will have been marked as
1356      * closed and the <code>Executor</code> that was passed as a parameter to abort
1357      * may still be executing tasks to release resources.
1358      * <p>
1359      * This method checks to see that there is an <code>SQLPermission</code>
1360      * object before allowing the method to proceed.  If a
1361      * <code>SecurityManager</code> exists and its
1362      * <code>checkPermission</code> method denies calling <code>abort</code>,
1363      * this method throws a
1364      * <code>java.lang.SecurityException</code>.
1365      * @param executor  The <code>Executor</code>  implementation which will
1366      * be used by <code>abort</code>.
1367      * @throws java.sql.SQLException if a database access error occurs or
1368      * the {@code executor} is {@code null},
1369      * @throws java.lang.SecurityException if a security manager exists and its
1370      *    <code>checkPermission</code> method denies calling <code>abort</code>
1371      * @see SecurityManager#checkPermission
1372      * @see Executor
1373      * @since 1.7
1374      */
1375     void abort(Executor executor) throws SQLException;
1376 
1377     /**
1378      *
1379      * Sets the maximum period a <code>Connection</code> or
1380      * objects created from the <code>Connection</code>
1381      * will wait for the database to reply to any one request. If any
1382      *  request remains unanswered, the waiting method will
1383      * return with a <code>SQLException</code>, and the <code>Connection</code>
1384      * or objects created from the <code>Connection</code>  will be marked as
1385      * closed. Any subsequent use of
1386      * the objects, with the exception of the <code>close</code>,
1387      * <code>isClosed</code> or <code>Connection.isValid</code>
1388      * methods, will result in  a <code>SQLException</code>.
1389      * <p>
1390      * <b>Note</b>: This method is intended to address a rare but serious
1391      * condition where network partitions can cause threads issuing JDBC calls
1392      * to hang uninterruptedly in socket reads, until the OS TCP-TIMEOUT
1393      * (typically 10 minutes). This method is related to the
1394      * {@link #abort abort() } method which provides an administrator
1395      * thread a means to free any such threads in cases where the
1396      * JDBC connection is accessible to the administrator thread.
1397      * The <code>setNetworkTimeout</code> method will cover cases where
1398      * there is no administrator thread, or it has no access to the
1399      * connection. This method is severe in it's effects, and should be
1400      * given a high enough value so it is never triggered before any more
1401      * normal timeouts, such as transaction timeouts.
1402      * <p>
1403      * JDBC driver implementations  may also choose to support the
1404      * {@code setNetworkTimeout} method to impose a limit on database
1405      * response time, in environments where no network is present.
1406      * <p>
1407      * Drivers may internally implement some or all of their API calls with
1408      * multiple internal driver-database transmissions, and it is left to the
1409      * driver implementation to determine whether the limit will be
1410      * applied always to the response to the API call, or to any
1411      * single  request made during the API call.
1412      * <p>
1413      *
1414      * This method can be invoked more than once, such as to set a limit for an
1415      * area of JDBC code, and to reset to the default on exit from this area.
1416      * Invocation of this method has no impact on already outstanding
1417      * requests.
1418      * <p>
1419      * The {@code Statement.setQueryTimeout()} timeout value is independent of the
1420      * timeout value specified in {@code setNetworkTimeout}. If the query timeout
1421      * expires  before the network timeout then the
1422      * statement execution will be canceled. If the network is still
1423      * active the result will be that both the statement and connection
1424      * are still usable. However if the network timeout expires before
1425      * the query timeout or if the statement timeout fails due to network
1426      * problems, the connection will be marked as closed, any resources held by
1427      * the connection will be released and both the connection and
1428      * statement will be unusable.
1429      *<p>
1430      * When the driver determines that the {@code setNetworkTimeout} timeout
1431      * value has expired, the JDBC driver marks the connection
1432      * closed and releases any resources held by the connection.
1433      * <p>
1434      *
1435      * This method checks to see that there is an <code>SQLPermission</code>
1436      * object before allowing the method to proceed.  If a
1437      * <code>SecurityManager</code> exists and its
1438      * <code>checkPermission</code> method denies calling
1439      * <code>setNetworkTimeout</code>, this method throws a
1440      * <code>java.lang.SecurityException</code>.
1441      *
1442      * @param executor  The <code>Executor</code>  implementation which will
1443      * be used by <code>setNetworkTimeout</code>.
1444      * @param milliseconds The time in milliseconds to wait for the database
1445      * operation
1446      *  to complete.  If the JDBC driver does not support milliseconds, the
1447      * JDBC driver will round the value up to the nearest second.  If the
1448      * timeout period expires before the operation
1449      * completes, a SQLException will be thrown.
1450      * A value of 0 indicates that there is not timeout for database operations.
1451      * @throws java.sql.SQLException if a database access error occurs, this
1452      * method is called on a closed connection,
1453      * the {@code executor} is {@code null},
1454      * or the value specified for <code>seconds</code> is less than 0.
1455      * @throws java.lang.SecurityException if a security manager exists and its
1456      *    <code>checkPermission</code> method denies calling
1457      * <code>setNetworkTimeout</code>.
1458      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1459      * this method
1460      * @see SecurityManager#checkPermission
1461      * @see Statement#setQueryTimeout
1462      * @see #getNetworkTimeout
1463      * @see #abort
1464      * @see Executor
1465      * @since 1.7
1466      */
1467     void setNetworkTimeout(Executor executor, int milliseconds) throws SQLException;
1468 
1469 
1470     /**
1471      * Retrieves the number of milliseconds the driver will
1472      * wait for a database request to complete.
1473      * If the limit is exceeded, a
1474      * <code>SQLException</code> is thrown.
1475      *
1476      * @return the current timeout limit in milliseconds; zero means there is
1477      *         no limit
1478      * @throws SQLException if a database access error occurs or
1479      * this method is called on a closed <code>Connection</code>
1480      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1481      * this method
1482      * @see #setNetworkTimeout
1483      * @since 1.7
1484      */
1485     int getNetworkTimeout() throws SQLException;
1486 }