Java > Open Source Codes > java > sql > Connection


1 /*
2  * @(#)Connection.java 1.43 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.sql;
9
10 /**
11  * <P>A connection (session) with a specific
12  * database. SQL statements are executed and results are returned
13  * within the context of a connection.
14  * <P>
15  * A <code>Connection</code> object's database is able to provide information
16  * describing its tables, its supported SQL grammar, its stored
17  * procedures, the capabilities of this connection, and so on. This
18  * information is obtained with the <code>getMetaData</code> method.
19  *
20  * <P><B>Note:</B> By default a <code>Connection</code> object is in
21  * auto-commit mode, which means that it automatically commits changes
22  * after executing each statement. If auto-commit mode has been
23  * disabled, the method <code>commit</code> must be called explicitly in
24  * order to commit changes; otherwise, database changes will not be saved.
25  * <P>
26  * A new <code>Connection</code> object created using the JDBC 2.1 core API
27  * has an initially empty type map associated with it. A user may enter a
28  * custom mapping for a UDT in this type map.
29  * When a UDT is retrieved from a data source with the
30  * method <code>ResultSet.getObject</code>, the <code>getObject</code> method
31  * will check the connection's type map to see if there is an entry for that
32  * UDT. If so, the <code>getObject</code> method will map the UDT to the
33  * class indicated. If there is no entry, the UDT will be mapped using the
34  * standard mapping.
35  * <p>
36  * A user may create a new type map, which is a <code>java.util.Map</code>
37  * object, make an entry in it, and pass it to the <code>java.sql</code>
38  * methods that can perform custom mapping. In this case, the method
39  * will use the given type map instead of the one associated with
40  * the connection.
41  * <p>
42  * For example, the following code fragment specifies that the SQL
43  * type <code>ATHLETES</code> will be mapped to the class
44  * <code>Athletes</code> in the Java programming language.
45  * The code fragment retrieves the type map for the <code>Connection
46  * </code> object <code>con</code>, inserts the entry into it, and then sets
47  * the type map with the new entry as the connection's type map.
48  * <pre>
49  * java.util.Map map = con.getTypeMap();
50  * map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
51  * con.setTypeMap(map);
52  * </pre>
53  *
54  * @see DriverManager#getConnection
55  * @see Statement
56  * @see ResultSet
57  * @see DatabaseMetaData
58  */
59 public interface Connection {
60
61     /**
62      * Creates a <code>Statement</code> object for sending
63      * SQL statements to the database.
64      * SQL statements without parameters are normally
65      * executed using <code>Statement</code> objects. If the same SQL statement
66      * is executed many times, it may be more efficient to use a
67      * <code>PreparedStatement</code> object.
68      * <P>
69      * Result sets created using the returned <code>Statement</code>
70      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
71      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
72      *
73      * @return a new default <code>Statement</code> object
74      * @exception SQLException if a database access error occurs
75      */
76     Statement createStatement() throws SQLException ;
77
78     /**
79      * Creates a <code>PreparedStatement</code> object for sending
80      * parameterized SQL statements to the database.
81      * <P>
82      * A SQL statement with or without IN parameters can be
83      * pre-compiled and stored in a <code>PreparedStatement</code> object. This
84      * object can then be used to efficiently execute this statement
85      * multiple times.
86      *
87      * <P><B>Note:</B> This method is optimized for handling
88      * parametric SQL statements that benefit from precompilation. If
89      * the driver supports precompilation,
90      * the method <code>prepareStatement</code> will send
91      * the statement to the database for precompilation. Some drivers
92      * may not support precompilation. In this case, the statement may
93      * not be sent to the database until the <code>PreparedStatement</code>
94      * object is executed. This has no direct effect on users; however, it does
95      * affect which methods throw certain <code>SQLException</code> objects.
96      * <P>
97      * Result sets created using the returned <code>PreparedStatement</code>
98      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
99      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
100      *
101      * @param sql an SQL statement that may contain one or more '?' IN
102      * parameter placeholders
103      * @return a new default <code>PreparedStatement</code> object containing the
104      * pre-compiled SQL statement
105      * @exception SQLException if a database access error occurs
106      */
107     PreparedStatement prepareStatement(String sql)
108     throws SQLException ;
109
110     /**
111      * Creates a <code>CallableStatement</code> object for calling
112      * database stored procedures.
113      * The <code>CallableStatement</code> object provides
114      * methods for setting up its IN and OUT parameters, and
115      * methods for executing the call to a stored procedure.
116      *
117      * <P><B>Note:</B> This method is optimized for handling stored
118      * procedure call statements. Some drivers may send the call
119      * statement to the database when the method <code>prepareCall</code>
120      * is done; others
121      * may wait until the <code>CallableStatement</code> object
122      * is executed. This has no
123      * direct effect on users; however, it does affect which method
124      * throws certain SQLExceptions.
125      * <P>
126      * Result sets created using the returned <code>CallableStatement</code>
127      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
128      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
129      *
130      * @param sql an SQL statement that may contain one or more '?'
131      * parameter placeholders. Typically this statement is a JDBC
132      * function call escape string.
133      * @return a new default <code>CallableStatement</code> object containing the
134      * pre-compiled SQL statement
135      * @exception SQLException if a database access error occurs
136      */
137     CallableStatement prepareCall(String sql) throws SQLException ;
138                         
139     /**
140      * Converts the given SQL statement into the system's native SQL grammar.
141      * A driver may convert the JDBC SQL grammar into its system's
142      * native SQL grammar prior to sending it. This method returns the
143      * native form of the statement that the driver would have sent.
144      *
145      * @param sql an SQL statement that may contain one or more '?'
146      * parameter placeholders
147      * @return the native form of this statement
148      * @exception SQLException if a database access error occurs
149      */
150     String nativeSQL(String sql) throws SQLException ;
151
152     /**
153      * Sets this connection's auto-commit mode to the given state.
154      * If a connection is in auto-commit mode, then all its SQL
155      * statements will be executed and committed as individual
156      * transactions. Otherwise, its SQL statements are grouped into
157      * transactions that are terminated by a call to either
158      * the method <code>commit</code> or the method <code>rollback</code>.
159      * By default, new connections are in auto-commit
160      * mode.
161      * <P>
162      * The commit occurs when the statement completes or the next
163      * execute occurs, whichever comes first. In the case of
164      * statements returning a <code>ResultSet</code> object,
165      * the statement completes when the last row of the
166      * <code>ResultSet</code> object has been retrieved or the
167      * <code>ResultSet</code> object has been closed. In advanced cases, a single
168      * statement may return multiple results as well as output
169      * parameter values. In these cases, the commit occurs when all results and
170      * output parameter values have been retrieved.
171      * <P>
172      * <B>NOTE:</B> If this method is called during a transaction, the
173      * transaction is committed.
174      *
175      * @param autoCommit <code>true</code> to enable auto-commit mode;
176      * <code>false</code> to disable it
177      * @exception SQLException if a database access error occurs
178      * @see #getAutoCommit
179      */
180     void setAutoCommit(boolean autoCommit) throws SQLException ;
181
182     /**
183      * Retrieves the current auto-commit mode for this <code>Connection</code>
184      * object.
185      *
186      * @return the current state of this <code>Connection</code> object's
187      * auto-commit mode
188      * @exception SQLException if a database access error occurs
189      * @see #setAutoCommit
190      */
191     boolean getAutoCommit() throws SQLException ;
192
193     /**
194      * Makes all changes made since the previous
195      * commit/rollback permanent and releases any database locks
196      * currently held by this <code>Connection</code> object.
197      * This method should be
198      * used only when auto-commit mode has been disabled.
199      *
200      * @exception SQLException if a database access error occurs or this
201      * <code>Connection</code> object is in auto-commit mode
202      * @see #setAutoCommit
203      */
204     void commit() throws SQLException ;
205
206     /**
207      * Undoes all changes made in the current transaction
208      * and releases any database locks currently held
209      * by this <code>Connection</code> object. This method should be
210      * used only when auto-commit mode has been disabled.
211      *
212      * @exception SQLException if a database access error occurs or this
213      * <code>Connection</code> object is in auto-commit mode
214      * @see #setAutoCommit
215      */
216     void rollback() throws SQLException ;
217
218     /**
219      * Releases this <code>Connection</code> object's database and JDBC resources
220      * immediately instead of waiting for them to be automatically released.
221      * <P>
222      * Calling the method <code>close</code> on a <code>Connection</code>
223      * object that is already closed is a no-op.
224      * <P>
225      * <B>Note:</B> A <code>Connection</code> object is automatically
226      * closed when it is garbage collected. Certain fatal errors also
227      * close a <code>Connection</code> object.
228      *
229      * @exception SQLException if a database access error occurs
230      */
231     void close() throws SQLException ;
232
233     /**
234      * Retrieves whether this <code>Connection</code> object has been
235      * closed. A connection is closed if the method <code>close</code>
236      * has been called on it or if certain fatal errors have occurred.
237      * This method is guaranteed to return <code>true</code> only when
238      * it is called after the method <code>Connection.close</code> has
239      * been called.
240      * <P>
241      * This method generally cannot be called to determine whether a
242      * connection to a database is valid or invalid. A typical client
243      * can determine that a connection is invalid by catching any
244      * exceptions that might be thrown when an operation is attempted.
245      *
246      * @return <code>true</code> if this <code>Connection</code> object
247      * is closed; <code>false</code> if it is still open
248      * @exception SQLException if a database access error occurs
249      */
250     boolean isClosed() throws SQLException ;
251
252     //======================================================================
253 // Advanced features:
254
255     /**
256      * Retrieves a <code>DatabaseMetaData</code> object that contains
257      * metadata about the database to which this
258      * <code>Connection</code> object represents a connection.
259      * The metadata includes information about the database's
260      * tables, its supported SQL grammar, its stored
261      * procedures, the capabilities of this connection, and so on.
262      *
263      * @return a <code>DatabaseMetaData</code> object for this
264      * <code>Connection</code> object
265      * @exception SQLException if a database access error occurs
266      */
267     DatabaseMetaData getMetaData() throws SQLException ;
268
269     /**
270      * Puts this connection in read-only mode as a hint to the driver to enable
271      * database optimizations.
272      *
273      * <P><B>Note:</B> This method cannot be called during a transaction.
274      *
275      * @param readOnly <code>true</code> enables read-only mode;
276      * <code>false</code> disables it
277      * @exception SQLException if a database access error occurs or this
278      * method is called during a transaction
279      */
280     void setReadOnly(boolean readOnly) throws SQLException ;
281
282     /**
283      * Retrieves whether this <code>Connection</code>
284      * object is in read-only mode.
285      *
286      * @return <code>true</code> if this <code>Connection</code> object
287      * is read-only; <code>false</code> otherwise
288      * @exception SQLException if a database access error occurs
289      */
290     boolean isReadOnly() throws SQLException ;
291
292     /**
293      * Sets the given catalog name in order to select
294      * a subspace of this <code>Connection</code> object's database
295      * in which to work.
296      * <P>
297      * If the driver does not support catalogs, it will
298      * silently ignore this request.
299      *
300      * @param catalog the name of a catalog (subspace in this
301      * <code>Connection</code> object's database) in which to work
302      * @exception SQLException if a database access error occurs
303      * @see #getCatalog
304      */
305     void setCatalog(String catalog) throws SQLException ;
306
307     /**
308      * Retrieves this <code>Connection</code> object's current catalog name.
309      *
310      * @return the current catalog name or <code>null</code> if there is none
311      * @exception SQLException if a database access error occurs
312      * @see #setCatalog
313      */
314     String getCatalog() throws SQLException ;
315
316     /**
317      * A constant indicating that transactions are not supported.
318      */
319     int TRANSACTION_NONE = 0;
320
321     /**
322      * A constant indicating that
323      * dirty reads, non-repeatable reads and phantom reads can occur.
324      * This level allows a row changed by one transaction to be read
325      * by another transaction before any changes in that row have been
326      * committed (a "dirty read"). If any of the changes are rolled back,
327      * the second transaction will have retrieved an invalid row.
328      */
329     int TRANSACTION_READ_UNCOMMITTED = 1;
330
331     /**
332      * A constant indicating that
333      * dirty reads are prevented; non-repeatable reads and phantom
334      * reads can occur. This level only prohibits a transaction
335      * from reading a row with uncommitted changes in it.
336      */
337     int TRANSACTION_READ_COMMITTED = 2;
338
339     /**
340      * A constant indicating that
341      * dirty reads and non-repeatable reads are prevented; phantom
342      * reads can occur. This level prohibits a transaction from
343      * reading a row with uncommitted changes in it, and it also
344      * prohibits the situation where one transaction reads a row,
345      * a second transaction alters the row, and the first transaction
346      * rereads the row, getting different values the second time
347      * (a "non-repeatable read").
348      */
349     int TRANSACTION_REPEATABLE_READ = 4;
350
351     /**
352      * A constant indicating that
353      * dirty reads, non-repeatable reads and phantom reads are prevented.
354      * This level includes the prohibitions in
355      * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the
356      * situation where one transaction reads all rows that satisfy
357      * a <code>WHERE</code> condition, a second transaction inserts a row that
358      * satisfies that <code>WHERE</code> condition, and the first transaction
359      * rereads for the same condition, retrieving the additional
360      * "phantom" row in the second read.
361      */
362     int TRANSACTION_SERIALIZABLE = 8;
363
364     /**
365      * Attempts to change the transaction isolation level for this
366      * <code>Connection</code> object to the one given.
367      * The constants defined in the interface <code>Connection</code>
368      * are the possible transaction isolation levels.
369      * <P>
370      * <B>Note:</B> If this method is called during a transaction, the result
371      * is implementation-defined.
372      *
373      * @param level one of the following <code>Connection</code> constants:
374      * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
375      * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
376      * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
377      * <code>Connection.TRANSACTION_SERIALIZABLE</code>.
378      * (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used
379      * because it specifies that transactions are not supported.)
380      * @exception SQLException if a database access error occurs
381      * or the given parameter is not one of the <code>Connection</code>
382      * constants
383      * @see DatabaseMetaData#supportsTransactionIsolationLevel
384      * @see #getTransactionIsolation
385      */
386     void setTransactionIsolation(int level) throws SQLException ;
387
388     /**
389      * Retrieves this <code>Connection</code> object's current
390      * transaction isolation level.
391      *
392      * @return the current transaction isolation level, which will be one
393      * of the following constants:
394      * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
395      * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
396      * <code>Connection.TRANSACTION_REPEATABLE_READ</code>,
397      * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
398      * <code>Connection.TRANSACTION_NONE</code>.
399      * @exception SQLException if a database access error occurs
400      * @see #setTransactionIsolation
401      */
402     int getTransactionIsolation() throws SQLException ;
403
404     /**
405      * Retrieves the first warning reported by calls on this
406      * <code>Connection</code> object. If there is more than one
407      * warning, subsequent warnings will be chained to the first one
408      * and can be retrieved by calling the method
409      * <code>SQLWarning.getNextWarning</code> on the warning
410      * that was retrieved previously.
411      * <P>
412      * This method may not be
413      * called on a closed connection; doing so will cause an
414      * <code>SQLException</code> to be thrown.
415      *
416      * <P><B>Note:</B> Subsequent warnings will be chained to this
417      * SQLWarning.
418      *
419      * @return the first <code>SQLWarning</code> object or <code>null</code>
420      * if there are none
421      * @exception SQLException if a database access error occurs or
422      * this method is called on a closed connection
423      * @see SQLWarning
424      */
425     SQLWarning getWarnings() throws SQLException ;
426
427     /**
428      * Clears all warnings reported for this <code>Connection</code> object.
429      * After a call to this method, the method <code>getWarnings</code>
430      * returns <code>null</code> until a new warning is
431      * reported for this <code>Connection</code> object.
432      *
433      * @exception SQLException if a database access error occurs
434      */
435     void clearWarnings() throws SQLException ;
436
437
438     //--------------------------JDBC 2.0-----------------------------
439
440     /**
441      * Creates a <code>Statement</code> object that will generate
442      * <code>ResultSet</code> objects with the given type and concurrency.
443      * This method is the same as the <code>createStatement</code> method
444      * above, but it allows the default result set
445      * type and concurrency to be overridden.
446      *
447      * @param resultSetType a result set type; one of
448      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
449      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
450      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
451      * @param resultSetConcurrency a concurrency type; one of
452      * <code>ResultSet.CONCUR_READ_ONLY</code> or
453      * <code>ResultSet.CONCUR_UPDATABLE</code>
454      * @return a new <code>Statement</code> object that will generate
455      * <code>ResultSet</code> objects with the given type and
456      * concurrency
457      * @exception SQLException if a database access error occurs
458      * or the given parameters are not <code>ResultSet</code>
459      * constants indicating type and concurrency
460      * @since 1.2
461      */
462     Statement createStatement(int resultSetType, int resultSetConcurrency)
463     throws SQLException ;
464
465     /**
466      *
467      * Creates a <code>PreparedStatement</code> object that will generate
468      * <code>ResultSet</code> objects with the given type and concurrency.
469      * This method is the same as the <code>prepareStatement</code> method
470      * above, but it allows the default result set
471      * type and concurrency to be overridden.
472      *
473      * @param sql a <code>String</code> object that is the SQL statement to
474      * be sent to the database; may contain one or more ? IN
475      * parameters
476      * @param resultSetType a result set type; one of
477      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
478      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
479      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
480      * @param resultSetConcurrency a concurrency type; one of
481      * <code>ResultSet.CONCUR_READ_ONLY</code> or
482      * <code>ResultSet.CONCUR_UPDATABLE</code>
483      * @return a new PreparedStatement object containing the
484      * pre-compiled SQL statement that will produce <code>ResultSet</code>
485      * objects with the given type and concurrency
486      * @exception SQLException if a database access error occurs
487      * or the given parameters are not <code>ResultSet</code>
488      * constants indicating type and concurrency
489      * @since 1.2
490      */
491     PreparedStatement prepareStatement(String sql, int resultSetType,
492                        int resultSetConcurrency)
493     throws SQLException ;
494
495     /**
496      * Creates a <code>CallableStatement</code> object that will generate
497      * <code>ResultSet</code> objects with the given type and concurrency.
498      * This method is the same as the <code>prepareCall</code> method
499      * above, but it allows the default result set
500      * type and concurrency to be overridden.
501      *
502      * @param sql a <code>String</code> object that is the SQL statement to
503      * be sent to the database; may contain on or more ? parameters
504      * @param resultSetType a result set type; one of
505      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
506      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
507      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
508      * @param resultSetConcurrency a concurrency type; one of
509      * <code>ResultSet.CONCUR_READ_ONLY</code> or
510      * <code>ResultSet.CONCUR_UPDATABLE</code>
511      * @return a new <code>CallableStatement</code> object containing the
512      * pre-compiled SQL statement that will produce <code>ResultSet</code>
513      * objects with the given type and concurrency
514      * @exception SQLException if a database access error occurs
515      * or the given parameters are not <code>ResultSet</code>
516      * constants indicating type and concurrency
517      * @since 1.2
518      */
519     CallableStatement prepareCall(String sql, int resultSetType,
520                   int resultSetConcurrency) throws SQLException ;
521
522     /**
523      * Retrieves the <code>Map</code> object associated with this
524      * <code>Connection</code> object.
525      * Unless the application has added an entry, the type map returned
526      * will be empty.
527      *
528      * @return the <code>java.util.Map</code> object associated
529      * with this <code>Connection</code> object
530      * @exception SQLException if a database access error occurs
531      * @since 1.2
532      * @see #setTypeMap
533      */
534     java.util.Map <String ,Class <?>> getTypeMap() throws SQLException ;
535
536     /**
537      * Installs the given <code>TypeMap</code> object as the type map for
538      * this <code>Connection</code> object. The type map will be used for the
539      * custom mapping of SQL structured types and distinct types.
540      *
541      * @param map the <code>java.util.Map</code> object to install
542      * as the replacement for this <code>Connection</code>
543      * object's default type map
544      * @exception SQLException if a database access error occurs or
545      * the given parameter is not a <code>java.util.Map</code>
546      * object
547      * @since 1.2
548      * @see #getTypeMap
549      */
550     void setTypeMap(java.util.Map <String ,Class <?>> map) throws SQLException ;
551
552     //--------------------------JDBC 3.0-----------------------------
553
554
555     /**
556      * Changes the holdability of <code>ResultSet</code> objects
557      * created using this <code>Connection</code> object to the given
558      * holdability.
559      *
560      * @param holdability a <code>ResultSet</code> holdability constant; one of
561      * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
562      * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
563      * @throws SQLException if a database access occurs, the given parameter
564      * is not a <code>ResultSet</code> constant indicating holdability,
565      * or the given holdability is not supported
566      * @see #getHoldability
567      * @see ResultSet
568      * @since 1.4
569      */
570     void setHoldability(int holdability) throws SQLException ;
571
572     /**
573      * Retrieves the current holdability of <code>ResultSet</code> objects
574      * created using this <code>Connection</code> object.
575      *
576      * @return the holdability, one of
577      * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
578      * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
579      * @throws SQLException if a database access occurs
580      * @see #setHoldability
581      * @see ResultSet
582      * @since 1.4
583      */
584     int getHoldability() throws SQLException ;
585
586     /**
587      * Creates an unnamed savepoint in the current transaction and
588      * returns the new <code>Savepoint</code> object that represents it.
589      *
590      * @return the new <code>Savepoint</code> object
591      * @exception SQLException if a database access error occurs
592      * or this <code>Connection</code> object is currently in
593      * auto-commit mode
594      * @see Savepoint
595      * @since 1.4
596      */
597     Savepoint setSavepoint() throws SQLException ;
598
599     /**
600      * Creates a savepoint with the given name in the current transaction
601      * and returns the new <code>Savepoint</code> object that represents it.
602      *
603      * @param name a <code>String</code> containing the name of the savepoint
604      * @return the new <code>Savepoint</code> object
605      * @exception SQLException if a database access error occurs
606      * or this <code>Connection</code> object is currently in
607      * auto-commit mode
608      * @see Savepoint
609      * @since 1.4
610      */
611     Savepoint setSavepoint(String name) throws SQLException ;
612
613     /**
614      * Undoes all changes made after the given <code>Savepoint</code> object
615      * was set.
616      * <P>
617      * This method should be used only when auto-commit has been disabled.
618      *
619      * @param savepoint the <code>Savepoint</code> object to roll back to
620      * @exception SQLException if a database access error occurs,
621      * the <code>Savepoint</code> object is no longer valid,
622      * or this <code>Connection</code> object is currently in
623      * auto-commit mode
624      * @see Savepoint
625      * @see #rollback
626      * @since 1.4
627      */
628     void rollback(Savepoint savepoint) throws SQLException ;
629
630     /**
631      * Removes the given <code>Savepoint</code> object from the current
632      * transaction. Any reference to the savepoint after it have been removed
633      * will cause an <code>SQLException</code> to be thrown.
634      *
635      * @param savepoint the <code>Savepoint</code> object to be removed
636      * @exception SQLException if a database access error occurs or
637      * the given <code>Savepoint</code> object is not a valid
638      * savepoint in the current transaction
639      * @since 1.4
640      */
641     void releaseSavepoint(Savepoint savepoint) throws SQLException ;
642
643     /**
644      * Creates a <code>Statement</code> object that will generate
645      * <code>ResultSet</code> objects with the given type, concurrency,
646      * and holdability.
647      * This method is the same as the <code>createStatement</code> method
648      * above, but it allows the default result set
649      * type, concurrency, and holdability to be overridden.
650      *
651      * @param resultSetType one of the following <code>ResultSet</code>
652      * constants:
653      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
654      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
655      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
656      * @param resultSetConcurrency one of the following <code>ResultSet</code>
657      * constants:
658      * <code>ResultSet.CONCUR_READ_ONLY</code> or
659      * <code>ResultSet.CONCUR_UPDATABLE</code>
660      * @param resultSetHoldability one of the following <code>ResultSet</code>
661      * constants:
662      * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
663      * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
664      * @return a new <code>Statement</code> object that will generate
665      * <code>ResultSet</code> objects with the given type,
666      * concurrency, and holdability
667      * @exception SQLException if a database access error occurs
668      * or the given parameters are not <code>ResultSet</code>
669      * constants indicating type, concurrency, and holdability
670      * @see ResultSet
671      * @since 1.4
672      */
673     Statement createStatement(int resultSetType, int resultSetConcurrency,
674                   int resultSetHoldability) throws SQLException ;
675
676     /**
677      * Creates a <code>PreparedStatement</code> object that will generate
678      * <code>ResultSet</code> objects with the given type, concurrency,
679      * and holdability.
680      * <P>
681      * This method is the same as the <code>prepareStatement</code> method
682      * above, but it allows the default result set
683      * type, concurrency, and holdability to be overridden.
684      *
685      * @param sql a <code>String</code> object that is the SQL statement to
686      * be sent to the database; may contain one or more ? IN
687      * parameters
688      * @param resultSetType one of the following <code>ResultSet</code>
689      * constants:
690      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
691      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
692      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
693      * @param resultSetConcurrency one of the following <code>ResultSet</code>
694      * constants:
695      * <code>ResultSet.CONCUR_READ_ONLY</code> or
696      * <code>ResultSet.CONCUR_UPDATABLE</code>
697      * @param resultSetHoldability one of the following <code>ResultSet</code>
698      * constants:
699      * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
700      * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
701      * @return a new <code>PreparedStatement</code> object, containing the
702      * pre-compiled SQL statement, that will generate
703      * <code>ResultSet</code> objects with the given type,
704      * concurrency, and holdability
705      * @exception SQLException if a database access error occurs
706      * or the given parameters are not <code>ResultSet</code>
707      * constants indicating type, concurrency, and holdability
708      * @see ResultSet
709      * @since 1.4
710      */
711     PreparedStatement prepareStatement(String sql, int resultSetType,
712                        int resultSetConcurrency, int resultSetHoldability)
713     throws SQLException ;
714
715     /**
716      * Creates a <code>CallableStatement</code> object that will generate
717      * <code>ResultSet</code> objects with the given type and concurrency.
718      * This method is the same as the <code>prepareCall</code> method
719      * above, but it allows the default result set
720      * type, result set concurrency type and holdability to be overridden.
721      *
722      * @param sql a <code>String</code> object that is the SQL statement to
723      * be sent to the database; may contain on or more ? parameters
724      * @param resultSetType one of the following <code>ResultSet</code>
725      * constants:
726      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
727      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
728      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
729      * @param resultSetConcurrency one of the following <code>ResultSet</code>
730      * constants:
731      * <code>ResultSet.CONCUR_READ_ONLY</code> or
732      * <code>ResultSet.CONCUR_UPDATABLE</code>
733      * @param resultSetHoldability one of the following <code>ResultSet</code>
734      * constants:
735      * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
736      * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
737      * @return a new <code>CallableStatement</code> object, containing the
738      * pre-compiled SQL statement, that will generate
739      * <code>ResultSet</code> objects with the given type,
740      * concurrency, and holdability
741      * @exception SQLException if a database access error occurs
742      * or the given parameters are not <code>ResultSet</code>
743      * constants indicating type, concurrency, and holdability
744      * @see ResultSet
745      * @since 1.4
746      */
747     CallableStatement prepareCall(String sql, int resultSetType,
748                   int resultSetConcurrency,
749                   int resultSetHoldability) throws SQLException ;
750
751
752     /**
753      * Creates a default <code>PreparedStatement</code> object that has
754      * the capability to retrieve auto-generated keys. The given constant
755      * tells the driver whether it should make auto-generated keys
756      * available for retrieval. This parameter is ignored if the SQL
757      * statement is not an <code>INSERT</code> statement.
758      * <P>
759      * <B>Note:</B> This method is optimized for handling
760      * parametric SQL statements that benefit from precompilation. If
761      * the driver supports precompilation,
762      * the method <code>prepareStatement</code> will send
763      * the statement to the database for precompilation. Some drivers
764      * may not support precompilation. In this case, the statement may
765      * not be sent to the database until the <code>PreparedStatement</code>
766      * object is executed. This has no direct effect on users; however, it does
767      * affect which methods throw certain SQLExceptions.
768      * <P>
769      * Result sets created using the returned <code>PreparedStatement</code>
770      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
771      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
772      *
773      * @param sql an SQL statement that may contain one or more '?' IN
774      * parameter placeholders
775      * @param autoGeneratedKeys a flag indicating whether auto-generated keys
776      * should be returned; one of
777      * <code>Statement.RETURN_GENERATED_KEYS</code> or
778      * <code>Statement.NO_GENERATED_KEYS</code>
779      * @return a new <code>PreparedStatement</code> object, containing the
780      * pre-compiled SQL statement, that will have the capability of
781      * returning auto-generated keys
782      * @exception SQLException if a database access error occurs
783      * or the given parameter is not a <code>Statement</code>
784      * constant indicating whether auto-generated keys should be
785      * returned
786      * @since 1.4
787      */
788     PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
789     throws SQLException ;
790
791     /**
792      * Creates a default <code>PreparedStatement</code> object capable
793      * of returning the auto-generated keys designated by the given array.
794      * This array contains the indexes of the columns in the target
795      * table that contain the auto-generated keys that should be made
796      * available. This array is ignored if the SQL
797      * statement is not an <code>INSERT</code> statement.
798      * <P>
799      * An SQL statement with or without IN parameters can be
800      * pre-compiled and stored in a <code>PreparedStatement</code> object. This
801      * object can then be used to efficiently execute this statement
802      * multiple times.
803      * <P>
804      * <B>Note:</B> This method is optimized for handling
805      * parametric SQL statements that benefit from precompilation. If
806      * the driver supports precompilation,
807      * the method <code>prepareStatement</code> will send
808      * the statement to the database for precompilation. Some drivers
809      * may not support precompilation. In this case, the statement may
810      * not be sent to the database until the <code>PreparedStatement</code>
811      * object is executed. This has no direct effect on users; however, it does
812      * affect which methods throw certain SQLExceptions.
813      * <P>
814      * Result sets created using the returned <code>PreparedStatement</code>
815      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
816      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
817      *
818      * @param sql an SQL statement that may contain one or more '?' IN
819      * parameter placeholders
820      * @param columnIndexes an array of column indexes indicating the columns
821      * that should be returned from the inserted row or rows
822      * @return a new <code>PreparedStatement</code> object, containing the
823      * pre-compiled statement, that is capable of returning the
824      * auto-generated keys designated by the given array of column
825      * indexes
826      * @exception SQLException if a database access error occurs
827      *
828      * @since 1.4
829      */
830     PreparedStatement prepareStatement(String sql, int columnIndexes[])
831     throws SQLException ;
832
833     /**
834      * Creates a default <code>PreparedStatement</code> object capable
835      * of returning the auto-generated keys designated by the given array.
836      * This array contains the names of the columns in the target
837      * table that contain the auto-generated keys that should be returned.
838      * This array is ignored if the SQL
839      * statement is not an <code>INSERT</code> statement.
840      * <P>
841      * An SQL statement with or without IN parameters can be
842      * pre-compiled and stored in a <code>PreparedStatement</code> object. This
843      * object can then be used to efficiently execute this statement
844      * multiple times.
845      * <P>
846      * <B>Note:</B> This method is optimized for handling
847      * parametric SQL statements that benefit from precompilation. If
848      * the driver supports precompilation,
849      * the method <code>prepareStatement</code> will send
850      * the statement to the database for precompilation. Some drivers
851      * may not support precompilation. In this case, the statement may
852      * not be sent to the database until the <code>PreparedStatement</code>
853      * object is executed. This has no direct effect on users; however, it does
854      * affect which methods throw certain SQLExceptions.
855      * <P>
856      * Result sets created using the returned <code>PreparedStatement</code>
857      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
858      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
859      *
860      * @param sql an SQL statement that may contain one or more '?' IN
861      * parameter placeholders
862      * @param columnNames an array of column names indicating the columns
863      * that should be returned from the inserted row or rows
864      * @return a new <code>PreparedStatement</code> object, containing the
865      * pre-compiled statement, that is capable of returning the
866      * auto-generated keys designated by the given array of column
867      * names
868      * @exception SQLException if a database access error occurs
869      *
870      * @since 1.4
871      */
872     PreparedStatement prepareStatement(String sql, String columnNames[])
873     throws SQLException ;
874
875
876 }
877

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags