History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/Connection.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/Connection.java+1486−0
@@ -0,0 +1,1486 @@
1+/*
2+ * Copyright (c) 1996, 2010, 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 conection 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+ * <p>
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+ * <p>
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+ * <p>
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+ * <p>
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+ * <p>
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+ * <p>
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+}