001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: import java.util.Map;
021:
022: /**
023: * A Connection represents a link from a Java application to a database. All SQL
024: * statements and results are returned within the context of a connection.
025: *
026: */
027: public interface Connection {
028:
029: /**
030: * A constant indicating that transactions are not supported.
031: */
032: public static final int TRANSACTION_NONE = 0;
033:
034: /**
035: * No dirty reads are permitted. Transactions may not read a row containing
036: * changes that have not yet been committed.
037: */
038: public static final int TRANSACTION_READ_COMMITTED = 2;
039:
040: /**
041: * Dirty reads (reading from table rows containing changes that have not yet
042: * been committed), non-repeatable reads (reading table rows more than once
043: * in a transaction but getting back different data because other
044: * transactions may have altered rows between reads), and phantom reads
045: * (retrieving additional "phantom" rows in the course of repeated table
046: * reads because other transactions may have inserted additional rows that
047: * satisfy an SQL <code>WHERE</code> clause) are <b>all permitted</b>.
048: */
049: public static final int TRANSACTION_READ_UNCOMMITTED = 1;
050:
051: /**
052: * A constant indicating that dirty reads and non-repeatable reads are
053: * prevented; phantom reads can occur.
054: */
055: public static final int TRANSACTION_REPEATABLE_READ = 4;
056:
057: /**
058: * Dirty reads (reading from table rows containing changes that have not yet
059: * been committed), non-repeatable reads (reading table rows more than once
060: * in a transaction but getting back different data because other
061: * transactions may have altered rows between reads), and phantom reads
062: * (retrieving additional "phantom" rows in the course of repeated table
063: * reads because other transactions may have inserted additional rows that
064: * satisfy an SQL <code>WHERE</code> clause) are <b>all prevented</b>.
065: */
066: public static final int TRANSACTION_SERIALIZABLE = 8;
067:
068: /**
069: * Throws away any warnings that may have arisen for this connection.
070: * Subsequent calls to {@link #getWarnings()} will return <code>null</code>
071: * up until a brand new warning condition occurs.
072: *
073: * @throws SQLException
074: * if there is a problem accessing the database
075: */
076: public void clearWarnings() throws SQLException;
077:
078: /**
079: * Causes the instant release of all database and driver connection
080: * resources associated with this object. Any subsequent invocations of this
081: * method will have no effect.
082: * <p>
083: * It is strongly recommended that all Connections are closed before they
084: * are dereferenced by the application ready for garbage collection. While
085: * the finalize method of the Connection will close the Connection before
086: * garbage collection takes place, it is not advisable to leave the close
087: * operation to take place in this way. Unpredictable performance may result
088: * from closing Connections in the finalizer.
089: *
090: * @throws SQLException
091: * if there is a problem accessing the database
092: */
093: public void close() throws SQLException;
094:
095: /**
096: * Commits all of the changes made subsequent to the last commit or rollback
097: * of the associated transaction. All locks in the database held by this
098: * connection are also relinquished. Calling this operation on connection
099: * objects in auto-commit mode is an error.
100: *
101: * @throws SQLException
102: * if there is a problem accessing the database or if the target
103: * connection instance is in auto-commit mode.
104: */
105: public void commit() throws SQLException;
106:
107: /**
108: * Returns a new instance of <code>Statement</code> for issuing SQL
109: * commands to the remote database.
110: * <p>
111: * ResultSets generated by the returned Statement will default to type
112: * <code>TYPE_FORWARD_ONLY</code> and concurrency level
113: * <code>CONCUR_READ_ONLY</code>.
114: *
115: * @return a <code>Statement</code> object with default settings.
116: * @throws SQLException
117: * if there is a problem accessing the database
118: */
119: public Statement createStatement() throws SQLException;
120:
121: /**
122: * Returns a new instance of <code>Statement</code> whose associated
123: * <code>ResultSet</code>s will have the characteristics specified in the
124: * type, concurrency and holdability arguments.
125: *
126: * @param resultSetType
127: * one of :
128: * <ul>
129: * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
130: * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
131: * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
132: * </ul>
133: * @param resultSetConcurrency
134: * one of :
135: * <ul>
136: * <li>{@link ResultSet#CONCUR_UPDATABLE}
137: * <li>{@link ResultSet#CONCUR_READ_ONLY}
138: * </ul>
139: * @return a new instance of <code>Statement</code> capable of
140: * manufacturing <code>ResultSet</code>s that satisfy the
141: * specified <code>resultSetType</code> and
142: * <code>resultSetConcurrency</code> values.
143: * @throws SQLException
144: * if there is a problem accessing the database
145: */
146: public Statement createStatement(int resultSetType,
147: int resultSetConcurrency) throws SQLException;
148:
149: /**
150: * Returns a new instance of <code>Statement</code> whose associated
151: * <code>ResultSet</code>s will have the characteristics specified in the
152: * type, concurrency and holdability arguments.
153: *
154: * @param resultSetType
155: * one of :
156: * <ul>
157: * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
158: * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
159: * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
160: * </ul>
161: * @param resultSetConcurrency
162: * one of :
163: * <ul>
164: * <li>{@link ResultSet#CONCUR_UPDATABLE}
165: * <li>{@link ResultSet#CONCUR_READ_ONLY}
166: * </ul>
167: * @param resultSetHoldability
168: * one of :
169: * <ul>
170: * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
171: * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
172: * </ul>
173: * @return a new instance of <code>Statement</code> capable of
174: * manufacturing <code>ResultSet</code>s that satisfy the
175: * specified <code>resultSetType</code>,
176: * <code>resultSetConcurrency</code> and
177: * <code>resultSetHoldability</code> values.
178: * @throws SQLException
179: * if there is a problem accessing the database
180: */
181: public Statement createStatement(int resultSetType,
182: int resultSetConcurrency, int resultSetHoldability)
183: throws SQLException;
184:
185: /**
186: * Returns a boolean indication of whether or not this connection is in the
187: * auto-commit operating mode.
188: *
189: * @return <code>true</code> if auto-commit is on, otherwise
190: * <code>false</code>
191: * @throws SQLException
192: * if there is a problem accessing the database
193: */
194: public boolean getAutoCommit() throws SQLException;
195:
196: /**
197: * Gets this Connection object's current catalog name.
198: *
199: * @return the catalog name. <code>null</code> if there is no catalog
200: * name.
201: * @throws SQLException
202: * if there is a problem accessing the database
203: */
204: public String getCatalog() throws SQLException;
205:
206: /**
207: * Returns the kind of holdability that any <code>ResultSet</code>s made
208: * from this instance will have.
209: *
210: * @return one of :
211: * <ul>
212: * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
213: * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
214: * </ul>
215: * @throws SQLException
216: * if there is a problem accessing the a database
217: */
218: public int getHoldability() throws SQLException;
219:
220: /**
221: * Gets the metadata about the database referenced by this connection. The
222: * returned <code>DatabaseMetaData</code> describes the database
223: * topography, available stored procedures, SQL syntax and so on.
224: *
225: * @return a <code>DatabaseMetaData</code> object containing the database
226: * description
227: * @throws SQLException
228: * if there is a problem accessing the a database
229: */
230: public DatabaseMetaData getMetaData() throws SQLException;
231:
232: /**
233: * Returns the present value of transaction isolation for this Connection
234: * instance.
235: *
236: * @return the transaction isolation value
237: * @throws SQLException
238: * if there is a problem accessing the database
239: * @see #TRANSACTION_NONE
240: * @see #TRANSACTION_READ_COMMITTED
241: * @see #TRANSACTION_READ_UNCOMMITTED
242: * @see #TRANSACTION_REPEATABLE_READ
243: * @see #TRANSACTION_SERIALIZABLE
244: */
245: public int getTransactionIsolation() throws SQLException;
246:
247: /**
248: * Returns the Type Map associated with this Connection object. The type map
249: * will be empty unless the application has added at least one entry.
250: *
251: * @return the Type Map as a <code>java.util.Map</code>
252: * @throws SQLException
253: * if there is a problem accessing the database
254: */
255: public Map<String, Class<?>> getTypeMap() throws SQLException;
256:
257: /**
258: * Gets the first instance of any <code>SQLWarning</code> objects that may
259: * have been created in the use of this connection. If at least one warning
260: * has occurred then this operation returns the first one reported. A
261: * <code>null</code> indicates that no warnings have occurred.
262: * <p>
263: * By invoking the {@link SQLWarning#getNextWarning()} method of the
264: * returned <code>SQLWarning</code> object it is possible to obtain all
265: * warning objects.
266: *
267: * @return the first warning as an SQLWarning object (may be
268: * <code>null</code>)
269: * @throws SQLException
270: * if there is a problem accessing the database or if the call
271: * has been made on a connection which has been previously
272: * closed.
273: */
274: public SQLWarning getWarnings() throws SQLException;
275:
276: /**
277: * Returns a boolean indication of whether or not this connection is in the
278: * closed state. The closed state may be entered into as a consequence of a
279: * successful invocation of the {@link #close()} method or else if an error
280: * has occurred that prevents the connection from functioning normally.
281: *
282: * @return <code>true</code> if closed, otherwise <code>false</code>
283: * @throws SQLException
284: * if there is a problem accessing the database
285: */
286: public boolean isClosed() throws SQLException;
287:
288: /**
289: * Returns a boolean indication of whether or not this connection is
290: * currently in read-only state.
291: *
292: * @return <code>true</code> if in read-only state, otherwise
293: * <code>false</code>.
294: * @throws SQLException
295: * if there is a problem accessing the database
296: */
297: public boolean isReadOnly() throws SQLException;
298:
299: /**
300: * Returns a string representation of the input SQL statement
301: * <code>sql</code> expressed in the underlying system's native SQL
302: * syntax.
303: *
304: * @param sql
305: * the JDBC form of an SQL statement.
306: * @return the SQL statement in native database format.
307: * @throws SQLException
308: * if there is a problem accessing the database
309: */
310: public String nativeSQL(String sql) throws SQLException;
311:
312: /**
313: * Returns a new instance of <code>CallableStatement</code> that may be
314: * used for making stored procedure calls to the database.
315: *
316: * @param sql
317: * the SQL statement that calls the stored function
318: * @return a new instance of <code>CallableStatement</code> representing
319: * the SQL statement. <code>ResultSet</code>s emitted from this
320: * <code>CallableStatement</code> will default to type
321: * {@link ResultSet#TYPE_FORWARD_ONLY} and concurrency
322: * {@link ResultSet#CONCUR_READ_ONLY}.
323: * @throws SQLException
324: * if a problem occurs accessing the database
325: */
326: public CallableStatement prepareCall(String sql)
327: throws SQLException;
328:
329: /**
330: * Returns a new instance of <code>CallableStatement</code> that may be
331: * used for making stored procedure calls to the database.
332: * <code>ResultSet</code>s emitted from this
333: * <code>CallableStatement</code> will satisfy the specified
334: * <code>resultSetType</code> and <code>resultSetConcurrency</code>
335: * values.
336: *
337: * @param sql
338: * the SQL statement
339: * @param resultSetType
340: * one of :
341: * <ul>
342: * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
343: * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
344: * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
345: * </ul>
346: * @param resultSetConcurrency
347: * one of :
348: * <ul>
349: * <li>{@link ResultSet#CONCUR_READ_ONLY}
350: * <li>{@link ResultSet#CONCUR_UPDATABLE}
351: * </ul>
352: * @return a new instance of <code>CallableStatement</code> representing
353: * the precompiled SQL statement. <code>ResultSet</code>s emitted
354: * from this <code>CallableStatement</code> will satisfy the
355: * specified <code>resultSetType</code> and
356: * <code>resultSetConcurrency</code> values.
357: * @throws SQLException
358: * if a problem occurs accessing the database
359: */
360: public CallableStatement prepareCall(String sql, int resultSetType,
361: int resultSetConcurrency) throws SQLException;
362:
363: /**
364: * Returns a new instance of <code>CallableStatement</code> that may be
365: * used for making stored procedure calls to the database. ResultSets
366: * created from this <code>CallableStatement</code> will have
367: * characteristics determined by the specified type, concurrency and
368: * holdability arguments.
369: *
370: * @param sql
371: * the SQL statement
372: * @param resultSetType
373: * one of :
374: * <ul>
375: * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
376: * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
377: * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
378: * </ul>
379: * @param resultSetConcurrency
380: * one of :
381: * <ul>
382: * <li>{@link ResultSet#CONCUR_READ_ONLY}
383: * <li>{@link ResultSet#CONCUR_UPDATABLE}
384: * </ul>
385: * @param resultSetHoldability
386: * one of :
387: * <ul>
388: * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
389: * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
390: * </ul>
391: * @return a new instance of <code>CallableStatement</code> representing
392: * the precompiled SQL statement. <code>ResultSet</code>s emitted
393: * from this <code>CallableStatement</code> will satisfy the
394: * specified <code>resultSetType</code>,
395: * <code>resultSetConcurrency</code> and
396: * <code>resultSetHoldability</code> values.
397: * @throws SQLException
398: * if a problem occurs accessing the database
399: */
400: public CallableStatement prepareCall(String sql, int resultSetType,
401: int resultSetConcurrency, int resultSetHoldability)
402: throws SQLException;
403:
404: /**
405: * Returns a new instance of <code>PreparedStatement</code> that may be
406: * used any number of times to execute parameterized requests on the
407: * database server.
408: * <p>
409: * Subject to JDBC driver support, this operation will attempt to send the
410: * precompiled version of the statement to the database. Alternatively, if
411: * the driver is not capable of flowing precompiled statements, the
412: * statement will not reach the database server until it is executed. This
413: * will have a bearing on precisely when <code>SQLException</code>
414: * instances get raised.
415: * <p>
416: * By default, ResultSets from the returned object will be
417: * {@link ResultSet#TYPE_FORWARD_ONLY} type with a
418: * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
419: *
420: * @param sql
421: * the SQL statement.
422: * @return the PreparedStatement containing the supplied SQL statement
423: * @throws SQLException
424: * if there is a problem accessing the database
425: */
426: public PreparedStatement prepareStatement(String sql)
427: throws SQLException;
428:
429: /**
430: * Creates a default PreparedStatement that can retrieve automatically
431: * generated keys. Parameter <code>autoGeneratedKeys</code> may be used to
432: * specify to the driver if such keys should be made accessible. This is
433: * only the case when <code>sql</code> is an insert statement.
434: * <p>
435: * An SQL statement which may have IN parameters can be stored and
436: * precompiled in a PreparedStatement. The PreparedStatement can then be
437: * used to execute the statement multiple times in an efficient way.
438: * <p>
439: * Subject to JDBC driver support, this operation will attempt to send the
440: * precompiled version of the statement to the database. Alternatively, if
441: * the driver is not capable of flowing precompiled statements, the
442: * statement will not reach the database server until it is executed. This
443: * will have a bearing on precisely when <code>SQLException</code>
444: * instances get raised.
445: * <p>
446: * By default, ResultSets from the returned object will be
447: * {@link ResultSet#TYPE_FORWARD_ONLY} type with a
448: * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
449: *
450: * @param sql
451: * the SQL statement.
452: * @param autoGeneratedKeys
453: * one of :
454: * <ul>
455: * <li>{@link Statement#RETURN_GENERATED_KEYS}
456: * <li>{@link Statement#NO_GENERATED_KEYS}
457: * </ul>
458: * @return a new <code>PreparedStatement</code> instance representing the
459: * input SQL statement.
460: * @throws SQLException
461: * if there is a problem accessing the database
462: */
463: public PreparedStatement prepareStatement(String sql,
464: int autoGeneratedKeys) throws SQLException;
465:
466: /**
467: * Creates a default PreparedStatement that can retrieve the auto-generated
468: * keys designated by a supplied array. If <code>sql</code> is an SQL
469: * <code>INSERT</code> statement, parameter <code>columnIndexes</code>
470: * is expected to hold the index values for each column in the statement's
471: * intended database table containing the autogenerated-keys of interest.
472: * Otherwise <code>columnIndexes</code> is ignored.
473: * <p>
474: * Subject to JDBC driver support, this operation will attempt to send the
475: * precompiled version of the statement to the database. Alternatively, if
476: * the driver is not capable of flowing precompiled statements, the
477: * statement will not reach the database server until it is executed. This
478: * will have a bearing on precisely when <code>SQLException</code>
479: * instances get raised.
480: * <p>
481: * By default, ResultSets from the returned object will be
482: * {@link ResultSet#TYPE_FORWARD_ONLY} type with a
483: * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
484: *
485: * @param sql
486: * the SQL statement.
487: * @param columnIndexes
488: * the indexes of the columns for which auto-generated keys
489: * should be made available.
490: * @return the PreparedStatement containing the supplied SQL statement
491: * @throws SQLException
492: * if a problem occurs accessing the database
493: */
494: public PreparedStatement prepareStatement(String sql,
495: int[] columnIndexes) throws SQLException;
496:
497: /**
498: * Creates a PreparedStatement that generates ResultSets with the specified
499: * values of <code>resultSetType</code> and
500: * <code>resultSetConcurrency</code>.
501: *
502: * @param sql
503: * the SQL statement. It can contain one or more '?' IN parameter
504: * placeholders
505: * @param resultSetType
506: * one of :
507: * <ul>
508: * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
509: * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
510: * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
511: * </ul>
512: * @param resultSetConcurrency
513: * one of :
514: * <ul>
515: * <li>{@link ResultSet#CONCUR_READ_ONLY}
516: * <li>{@link ResultSet#CONCUR_UPDATABLE}
517: * </ul>
518: * @return a new instance of <code>PreparedStatement</code> containing the
519: * SQL statement <code>sql</code>. <code>ResultSet</code>s
520: * emitted from this <code>PreparedStatement</code> will satisfy
521: * the specified <code>resultSetType</code> and
522: * <code>resultSetConcurrency</code> values.
523: * @throws SQLException
524: * if a problem occurs accessing the database
525: */
526: public PreparedStatement prepareStatement(String sql,
527: int resultSetType, int resultSetConcurrency)
528: throws SQLException;
529:
530: /**
531: * Creates a PreparedStatement that generates ResultSets with the specified
532: * type, concurrency and holdability
533: *
534: * @param sql
535: * the SQL statement. It can contain one or more '?' IN parameter
536: * placeholders
537: * @param resultSetType
538: * one of :
539: * <ul>
540: * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
541: * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
542: * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
543: * </ul>
544: * @param resultSetConcurrency
545: * one of :
546: * <ul>
547: * <li>{@link ResultSet#CONCUR_READ_ONLY}
548: * <li>{@link ResultSet#CONCUR_UPDATABLE}
549: * </ul>
550: * @param resultSetHoldability
551: * one of :
552: * <ul>
553: * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
554: * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
555: * </ul>
556: *
557: * @return a new instance of <code>PreparedStatement</code> containing the
558: * SQL statement <code>sql</code>. <code>ResultSet</code>s
559: * emitted from this <code>PreparedStatement</code> will satisfy
560: * the specified <code>resultSetType</code>,
561: * <code>resultSetConcurrency</code> and
562: * <code>resultSetHoldability</code> values.
563: * @throws SQLException
564: * if a problem occurs accessing the database
565: */
566: public PreparedStatement prepareStatement(String sql,
567: int resultSetType, int resultSetConcurrency,
568: int resultSetHoldability) throws SQLException;
569:
570: /**
571: * Creates a default PreparedStatement that can retrieve the auto-generated
572: * keys designated by a supplied array. If <code>sql</code> is an SQL
573: * <code>INSERT</code> statement, <code>columnNames</code> is expected
574: * to hold the names of each column in the statement's associated database
575: * table containing the autogenerated-keys of interest. Otherwise
576: * <code>columnNames</code> is ignored.
577: * <p>
578: * Subject to JDBC driver support, this operation will attempt to send the
579: * precompiled version of the statement to the database. Alternatively, if
580: * the driver is not capable of flowing precompiled statements, the
581: * statement will not reach the database server until it is executed. This
582: * will have a bearing on precisely when <code>SQLException</code>
583: * instances get raised.
584: * <p>
585: * By default, ResultSets from the returned object will be
586: * {@link ResultSet#TYPE_FORWARD_ONLY} type with a
587: * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
588: *
589: * @param sql
590: * the SQL statement.
591: * @param columnNames
592: * the names of the columns for which auto-generated keys should
593: * be made available.
594: * @return the PreparedStatement containing the supplied SQL statement
595: * @throws SQLException
596: * if a problem occurs accessing the database
597: */
598: public PreparedStatement prepareStatement(String sql,
599: String[] columnNames) throws SQLException;
600:
601: /**
602: * Releases <code>savepoint</code> from the present transaction. Once
603: * removed, the <code>Savepoint</code> is considered invalid and should
604: * not be referenced further.
605: *
606: * @param savepoint
607: * the object targeted for removal
608: * @throws SQLException
609: * if there is a problem with accessing the database or if
610: * <code>savepoint</code> is considered not valid in this
611: * transaction.
612: */
613: public void releaseSavepoint(Savepoint savepoint)
614: throws SQLException;
615:
616: /**
617: * Rolls back all updates made so far in this transaction as well as
618: * relinquishing all acquired database locks. It is an error to invoke this
619: * operation when in auto-commit mode.
620: *
621: * @throws SQLException
622: * if there is a problem with the database or if the method is
623: * called while in auto-commit mode of operation.
624: */
625: public void rollback() throws SQLException;
626:
627: /**
628: * Undoes all changes made after the supplied Savepoint object was set. This
629: * method should only be used when auto-commit mode is disabled.
630: *
631: * @param savepoint
632: * the Savepoint to roll back to
633: * @throws SQLException
634: * if there is a problem accessing the database
635: */
636: public void rollback(Savepoint savepoint) throws SQLException;
637:
638: /**
639: * Sets this connection's auto-commit mode on or off.
640: * <p>
641: * Putting a Connection into auto-commit mode means that all associated SQL
642: * statements will be run and committed in their own separate transactions.
643: * Alternatively, auto-commit set to off means that associated SQL
644: * statements get grouped into transactions that need to be completed by
645: * explicit calls to either the {@link #commit()} or {@link #rollback()}
646: * methods.
647: * <p>
648: * Auto-commit is the default mode for new connection instances.
649: * <p>
650: * When in this mode, commits will automatically occur upon successful SQL
651: * statement completion or upon successful completion of an execute.
652: * Statements are not considered successfully complete until all associated
653: * <code>ResultSet</code>s and output parameters have been obtained or
654: * closed.
655: * <p>
656: * Calling this operation during an uncommitted transaction will result in
657: * it being committed.
658: *
659: * @param autoCommit
660: * boolean indication of whether to put the target connection
661: * into auto-commit mode (<code>true</code>) or not (<code>false</code>)
662: *
663: * @throws SQLException
664: * if there is a problem accessing the database
665: */
666: public void setAutoCommit(boolean autoCommit) throws SQLException;
667:
668: /**
669: * Sets the catalog name for this connection. This is used to select a
670: * subspace of the database for future work. If the driver does not support
671: * catalog names, this method is ignored.
672: *
673: * @param catalog
674: * the catalog name to use.
675: * @throws SQLException
676: * if there is a problem accessing the database
677: */
678: public void setCatalog(String catalog) throws SQLException;
679:
680: /**
681: * Sets the holdability of ResultSets created by this Connection.
682: *
683: * @param holdability
684: * one of :
685: * <ul>
686: * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
687: * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
688: * <li>
689: * </ul>
690: * @throws SQLException
691: * if there is a problem accessing the database
692: */
693: public void setHoldability(int holdability) throws SQLException;
694:
695: /**
696: * Sets this connection to read-only mode.
697: * <p>
698: * This serves as a hint to the driver, which can enable database
699: * optimizations.
700: *
701: * @param readOnly
702: * true to set the Connection to read only mode. false disables
703: * read-only mode
704: * @throws SQLException
705: * if there is a problem accessing the database
706: */
707: public void setReadOnly(boolean readOnly) throws SQLException;
708:
709: /**
710: * Creates an unnamed Savepoint in the current transaction.
711: *
712: * @return a Savepoint object for this savepoint.
713: * @throws SQLException
714: * if there is a problem accessing the database
715: */
716: public Savepoint setSavepoint() throws SQLException;
717:
718: /**
719: * Creates a named Savepoint in the current transaction.
720: *
721: * @param name
722: * the name to use for the new Savepoint.
723: * @return a Savepoint object for this savepoint.
724: * @throws SQLException
725: * if there is a problem accessing the database
726: */
727: public Savepoint setSavepoint(String name) throws SQLException;
728:
729: /**
730: * Sets the transaction isolation level for this Connection.
731: * <p>
732: * If this method is called during a transaction, the results are
733: * implementation defined.
734: *
735: * @param level
736: * the new transaction isolation level to use from the following
737: * list of possible values :
738: * <ul>
739: * <li>{@link #TRANSACTION_READ_COMMITTED}
740: * <li>{@link #TRANSACTION_READ_UNCOMMITTED}
741: * <li>{@link #TRANSACTION_REPEATABLE_READ}
742: * <li>{@link #TRANSACTION_SERIALIZABLE}
743: * </ul>
744: * @throws SQLException
745: * if there is a problem with the database or if the value of
746: * <code>level</code> is not one of the expected constant
747: * values.
748: */
749: public void setTransactionIsolation(int level) throws SQLException;
750:
751: /**
752: * Sets the <code>TypeMap</code> for this connection. The input
753: * <code>map</code> should contain mappings between complex Java and SQL
754: * types.
755: *
756: * @param map
757: * the new type map
758: * @throws SQLException
759: * if there is a problem accessing the database or if
760: * <code>map</code> is not an instance of {@link Map}.
761: */
762: public void setTypeMap(Map<String, Class<?>> map)
763: throws SQLException;
764: }
|