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 *
277 * @exception SQLException SQLException if a database access error occurs
278 */
279 void close() throws SQLException;
280
281 /**
282 * Retrieves whether this <code>Connection</code> object has been
283 * closed. A connection is closed if the method <code>close</code>
284 * has been called on it or if certain fatal errors have occurred.
285 * This method is guaranteed to return <code>true</code> only when
286 * it is called after the method <code>Connection.close</code> has
287 * been called.
288 * <P>
289 * This method generally cannot be called to determine whether a
290 * connection to a database is valid or invalid. A typical client
291 * can determine that a connection is invalid by catching any
292 * exceptions that might be thrown when an operation is attempted.
293 *
294 * @return <code>true</code> if this <code>Connection</code> object
295 * is closed; <code>false</code> if it is still open
296 * @exception SQLException if a database access error occurs
297 */
318 /**
319 * Puts this connection in read-only mode as a hint to the driver to enable
320 * database optimizations.
321 *
322 * <P><B>Note:</B> This method cannot be called during a transaction.
323 *
324 * @param readOnly <code>true</code> enables read-only mode;
325 * <code>false</code> disables it
326 * @exception SQLException if a database access error occurs, this
327 * method is called on a closed connection or this
328 * method is called during a transaction
329 */
330 void setReadOnly(boolean readOnly) throws SQLException;
331
332 /**
333 * Retrieves whether this <code>Connection</code>
334 * object is in read-only mode.
335 *
336 * @return <code>true</code> if this <code>Connection</code> object
337 * is read-only; <code>false</code> otherwise
338 * @exception SQLException SQLException if a database access error occurs
339 * or this method is called on a closed connection
340 */
341 boolean isReadOnly() throws SQLException;
342
343 /**
344 * Sets the given catalog name in order to select
345 * a subspace of this <code>Connection</code> object's database
346 * in which to work.
347 * <P>
348 * If the driver does not support catalogs, it will
349 * silently ignore this request.
350 * <p>
351 * Calling {@code setCatalog} has no effect on previously created or prepared
352 * {@code Statement} objects. It is implementation defined whether a DBMS
353 * prepare operation takes place immediately when the {@code Connection}
354 * method {@code prepareStatement} or {@code prepareCall} is invoked.
355 * For maximum portability, {@code setCatalog} should be called before a
356 * {@code Statement} is created or prepared.
357 *
358 * @param catalog the name of a catalog (subspace in this
475 * called on a closed connection; doing so will cause an
476 * <code>SQLException</code> to be thrown.
477 *
478 * <P><B>Note:</B> Subsequent warnings will be chained to this
479 * SQLWarning.
480 *
481 * @return the first <code>SQLWarning</code> object or <code>null</code>
482 * if there are none
483 * @exception SQLException if a database access error occurs or
484 * this method is called on a closed connection
485 * @see SQLWarning
486 */
487 SQLWarning getWarnings() throws SQLException;
488
489 /**
490 * Clears all warnings reported for this <code>Connection</code> object.
491 * After a call to this method, the method <code>getWarnings</code>
492 * returns <code>null</code> until a new warning is
493 * reported for this <code>Connection</code> object.
494 *
495 * @exception SQLException SQLException if a database access error occurs
496 * or this method is called on a closed connection
497 */
498 void clearWarnings() throws SQLException;
499
500
501 //--------------------------JDBC 2.0-----------------------------
502
503 /**
504 * Creates a <code>Statement</code> object that will generate
505 * <code>ResultSet</code> objects with the given type and concurrency.
506 * This method is the same as the <code>createStatement</code> method
507 * above, but it allows the default result set
508 * type and concurrency to be overridden.
509 * The holdability of the created result sets can be determined by
510 * calling {@link #getHoldability}.
511 *
512 * @param resultSetType a result set type; one of
513 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
514 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
515 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
615 * Map<String,Class<?>> myMap = con.getTypeMap();
616 * myMap.put("mySchemaName.ATHLETES", Athletes.class);
617 * con.setTypeMap(myMap);
618 * </pre>
619 * @return the <code>java.util.Map</code> object associated
620 * with this <code>Connection</code> object
621 * @exception SQLException if a database access error occurs
622 * or this method is called on a closed connection
623 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
624 * this method
625 * @since 1.2
626 * @see #setTypeMap
627 */
628 java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
629
630 /**
631 * Installs the given <code>TypeMap</code> object as the type map for
632 * this <code>Connection</code> object. The type map will be used for the
633 * custom mapping of SQL structured types and distinct types.
634 * <p>
635 * You must set the the values for the <code>TypeMap</code> prior to
636 * callng <code>setMap</code> as a JDBC driver may create an internal copy
637 * of the <code>TypeMap</code>:
638 *
639 * <pre>
640 * Map myMap<String,Class<?>> = new HashMap<String,Class<?>>();
641 * myMap.put("mySchemaName.ATHLETES", Athletes.class);
642 * con.setTypeMap(myMap);
643 * </pre>
644 * @param map the <code>java.util.Map</code> object to install
645 * as the replacement for this <code>Connection</code>
646 * object's default type map
647 * @exception SQLException if a database access error occurs, this
648 * method is called on a closed connection or
649 * the given parameter is not a <code>java.util.Map</code>
650 * object
651 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
652 * this method
653 * @since 1.2
654 * @see #getTypeMap
655 */
656 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
657
658 //--------------------------JDBC 3.0-----------------------------
659
660
661 /**
662 * Changes the default holdability of <code>ResultSet</code> objects
663 * created using this <code>Connection</code> object to the given
664 * holdability. The default holdability of <code>ResultSet</code> objects
665 * can be be determined by invoking
666 * {@link DatabaseMetaData#getResultSetHoldability}.
667 *
668 * @param holdability a <code>ResultSet</code> holdability constant; one of
669 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
670 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
671 * @throws SQLException if a database access occurs, this method is called
672 * on a closed connection, or the given parameter
673 * is not a <code>ResultSet</code> constant indicating holdability
674 * @exception SQLFeatureNotSupportedException if the given holdability is not supported
675 * @see #getHoldability
676 * @see DatabaseMetaData#getResultSetHoldability
677 * @see ResultSet
678 * @since 1.4
679 */
680 void setHoldability(int holdability) throws SQLException;
681
682 /**
683 * Retrieves the current holdability of <code>ResultSet</code> objects
684 * created using this <code>Connection</code> object.
685 *
|
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 *
277 * @exception SQLException if a database access error occurs
278 */
279 void close() throws SQLException;
280
281 /**
282 * Retrieves whether this <code>Connection</code> object has been
283 * closed. A connection is closed if the method <code>close</code>
284 * has been called on it or if certain fatal errors have occurred.
285 * This method is guaranteed to return <code>true</code> only when
286 * it is called after the method <code>Connection.close</code> has
287 * been called.
288 * <P>
289 * This method generally cannot be called to determine whether a
290 * connection to a database is valid or invalid. A typical client
291 * can determine that a connection is invalid by catching any
292 * exceptions that might be thrown when an operation is attempted.
293 *
294 * @return <code>true</code> if this <code>Connection</code> object
295 * is closed; <code>false</code> if it is still open
296 * @exception SQLException if a database access error occurs
297 */
318 /**
319 * Puts this connection in read-only mode as a hint to the driver to enable
320 * database optimizations.
321 *
322 * <P><B>Note:</B> This method cannot be called during a transaction.
323 *
324 * @param readOnly <code>true</code> enables read-only mode;
325 * <code>false</code> disables it
326 * @exception SQLException if a database access error occurs, this
327 * method is called on a closed connection or this
328 * method is called during a transaction
329 */
330 void setReadOnly(boolean readOnly) throws SQLException;
331
332 /**
333 * Retrieves whether this <code>Connection</code>
334 * object is in read-only mode.
335 *
336 * @return <code>true</code> if this <code>Connection</code> object
337 * is read-only; <code>false</code> otherwise
338 * @exception SQLException if a database access error occurs
339 * or this method is called on a closed connection
340 */
341 boolean isReadOnly() throws SQLException;
342
343 /**
344 * Sets the given catalog name in order to select
345 * a subspace of this <code>Connection</code> object's database
346 * in which to work.
347 * <P>
348 * If the driver does not support catalogs, it will
349 * silently ignore this request.
350 * <p>
351 * Calling {@code setCatalog} has no effect on previously created or prepared
352 * {@code Statement} objects. It is implementation defined whether a DBMS
353 * prepare operation takes place immediately when the {@code Connection}
354 * method {@code prepareStatement} or {@code prepareCall} is invoked.
355 * For maximum portability, {@code setCatalog} should be called before a
356 * {@code Statement} is created or prepared.
357 *
358 * @param catalog the name of a catalog (subspace in this
475 * called on a closed connection; doing so will cause an
476 * <code>SQLException</code> to be thrown.
477 *
478 * <P><B>Note:</B> Subsequent warnings will be chained to this
479 * SQLWarning.
480 *
481 * @return the first <code>SQLWarning</code> object or <code>null</code>
482 * if there are none
483 * @exception SQLException if a database access error occurs or
484 * this method is called on a closed connection
485 * @see SQLWarning
486 */
487 SQLWarning getWarnings() throws SQLException;
488
489 /**
490 * Clears all warnings reported for this <code>Connection</code> object.
491 * After a call to this method, the method <code>getWarnings</code>
492 * returns <code>null</code> until a new warning is
493 * reported for this <code>Connection</code> object.
494 *
495 * @exception SQLException if a database access error occurs
496 * or this method is called on a closed connection
497 */
498 void clearWarnings() throws SQLException;
499
500
501 //--------------------------JDBC 2.0-----------------------------
502
503 /**
504 * Creates a <code>Statement</code> object that will generate
505 * <code>ResultSet</code> objects with the given type and concurrency.
506 * This method is the same as the <code>createStatement</code> method
507 * above, but it allows the default result set
508 * type and concurrency to be overridden.
509 * The holdability of the created result sets can be determined by
510 * calling {@link #getHoldability}.
511 *
512 * @param resultSetType a result set type; one of
513 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
514 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
515 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
615 * Map<String,Class<?>> myMap = con.getTypeMap();
616 * myMap.put("mySchemaName.ATHLETES", Athletes.class);
617 * con.setTypeMap(myMap);
618 * </pre>
619 * @return the <code>java.util.Map</code> object associated
620 * with this <code>Connection</code> object
621 * @exception SQLException if a database access error occurs
622 * or this method is called on a closed connection
623 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
624 * this method
625 * @since 1.2
626 * @see #setTypeMap
627 */
628 java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
629
630 /**
631 * Installs the given <code>TypeMap</code> object as the type map for
632 * this <code>Connection</code> object. The type map will be used for the
633 * custom mapping of SQL structured types and distinct types.
634 * <p>
635 * You must set the values for the <code>TypeMap</code> prior to
636 * callng <code>setMap</code> as a JDBC driver may create an internal copy
637 * of the <code>TypeMap</code>:
638 *
639 * <pre>
640 * Map myMap<String,Class<?>> = new HashMap<String,Class<?>>();
641 * myMap.put("mySchemaName.ATHLETES", Athletes.class);
642 * con.setTypeMap(myMap);
643 * </pre>
644 * @param map the <code>java.util.Map</code> object to install
645 * as the replacement for this <code>Connection</code>
646 * object's default type map
647 * @exception SQLException if a database access error occurs, this
648 * method is called on a closed connection or
649 * the given parameter is not a <code>java.util.Map</code>
650 * object
651 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
652 * this method
653 * @since 1.2
654 * @see #getTypeMap
655 */
656 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
657
658 //--------------------------JDBC 3.0-----------------------------
659
660
661 /**
662 * Changes the default holdability of <code>ResultSet</code> objects
663 * created using this <code>Connection</code> object to the given
664 * holdability. The default holdability of <code>ResultSet</code> objects
665 * can be determined by invoking
666 * {@link DatabaseMetaData#getResultSetHoldability}.
667 *
668 * @param holdability a <code>ResultSet</code> holdability constant; one of
669 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
670 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
671 * @throws SQLException if a database access occurs, this method is called
672 * on a closed connection, or the given parameter
673 * is not a <code>ResultSet</code> constant indicating holdability
674 * @exception SQLFeatureNotSupportedException if the given holdability is not supported
675 * @see #getHoldability
676 * @see DatabaseMetaData#getResultSetHoldability
677 * @see ResultSet
678 * @since 1.4
679 */
680 void setHoldability(int holdability) throws SQLException;
681
682 /**
683 * Retrieves the current holdability of <code>ResultSet</code> objects
684 * created using this <code>Connection</code> object.
685 *
|