diff options
Diffstat (limited to 'libjava/java/sql/Connection.java')
| -rw-r--r-- | libjava/java/sql/Connection.java | 786 |
1 files changed, 372 insertions, 414 deletions
diff --git a/libjava/java/sql/Connection.java b/libjava/java/sql/Connection.java index 8583fdb..3f4d7de 100644 --- a/libjava/java/sql/Connection.java +++ b/libjava/java/sql/Connection.java @@ -1,5 +1,5 @@ /* Connection.java -- Manage a database connection. - Copyright (C) 1999, 2000 Free Software Foundation, Inc. + Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -41,422 +41,380 @@ package java.sql; import java.util.Map; /** - * This interface provides methods for managing a connection to a database. - * - * @author Aaron M. Renn (arenn@urbanophile.com) - */ -public interface Connection + * This interface provides methods for managing a connection to a database. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + */ +public interface Connection { - -/** - * This transaction isolation level indicates that transactions are not - * supported. - */ -public static final int TRANSACTION_NONE = 0; - -/** - * This transaction isolation level indicates that one transaction can - * read modifications by other transactions before the other transactions - * have committed their changes. This could result in invalid reads. - */ -public static final int TRANSACTION_READ_UNCOMMITTED = 1; - -/** - * This transaction isolation leve indicates that only committed data from - * other transactions will be read. If a transaction reads a row, then - * another transaction commits a change to that row, the first transaction - * would retrieve the changed row on subsequent reads of the same row. - */ -public static final int TRANSACTION_READ_COMMITTED = 2; - -/** - * This transaction isolation level indicates that only committed data from - * other transactions will be read. It also ensures that data read from - * a row will not be different on a subsequent read even if another - * transaction commits a change. - */ -public static final int TRANSACTION_REPEATABLE_READ = 4; - -/** - * This transaction isolation level indicates that only committed data from - * other transactions will be read. It also ensures that data read from - * a row will not be different on a subsequent read even if another - * transaction commits a change. Additionally, rows modified by other - * transactions will not affect the result set returned during subsequent - * executions of the same WHERE clause in this transaction. - */ -public static final int TRANSACTION_SERIALIZABLE = 8; - -/*************************************************************************/ - -/** - * This method creates a new SQL statement. The default result set type - * and concurrency will be used. - * - * @return A new <code>Statement</code> object. - * - * @exception SQLException If an error occurs. - * - * @see Statement - */ -public abstract Statement -createStatement() throws SQLException; - -/*************************************************************************/ - -/** - * This method creates a new SQL statement with the specified type and - * concurrency. Valid values for these parameters are specified in the - * <code>ResultSet</code> class. - * - * @param resultSetType The type of result set to use for this statement. - * @param resultSetConcurrency. The type of concurrency to be used in - * the result set for this statement. - * - * @return A new <code>Statement</code> object. - * - * @exception SQLException If an error occurs. - * - * @see Statement - * @see ResultSet - */ -public abstract Statement -createStatement(int resultSetType, int resultSetConcurrency) - throws SQLException; - -/*************************************************************************/ - -/** - * This method creates a new <code>PreparedStatement</code> for the specified - * SQL string. This method is designed for use with parameterized - * statements. The default result set type and concurrency will be used. - * - * @param The SQL statement to use in creating this - * <code>PreparedStatement</code>. - * - * @return A new <code>PreparedStatement</code>. - * - * @exception SQLException If an error occurs. - * - * @see PreparedStatement - */ -public abstract PreparedStatement -prepareStatement(String sql) throws SQLException; - -/*************************************************************************/ - -/** - * This method creates a new <code>PreparedStatement</code> for the specified - * SQL string. This method is designed for use with parameterized - * statements. The specified result set type and concurrency will be used. - * Valid values for these parameters are specified in the - * <code>ResultSet</code> class. - * - * @param The SQL statement to use in creating this - * <code>PreparedStatement</code>. - * @param resultSetType The type of result set to use for this statement. - * @param resultSetConcurrency. The type of concurrency to be used in - * the result set for this statement. - * - * @return A new <code>PreparedStatement</code>. - * - * @exception SQLException If an error occurs. - * - * @see PreparedStatement - * @see ResultSet - */ -public abstract PreparedStatement -prepareStatement(String sql, int resultSetType, int resultSetConcurrency) - throws SQLException; - -/*************************************************************************/ - -/** - * This method creates a new <code>CallableStatement</code> for the - * specified SQL string. Thie method is designed to be used with - * stored procedures. The default result set type and concurrency - * will be used. - * - * @param The SQL statement to use in creating this - * <code>CallableStatement</code>. - * - * @return A new <code>CallableStatement</code>. - * - * @exception SQLException If an error occurs. - * - * @see CallableStatement - */ -public abstract CallableStatement -prepareCall(String sql) throws SQLException; - -/*************************************************************************/ - -/** - * This method creates a new <code>CallableStatement</code> for the - * specified SQL string. Thie method is designed to be used with - * stored procedures. The specified result set type and concurrency - * will be used. Valid values for these parameters are specified in the - * <code>ResultSet</code> class. - * - * @param The SQL statement to use in creating this - * <code>PreparedStatement</code>. - * @param resultSetType The type of result set to use for this statement. - * @param resultSetConcurrency. The type of concurrency to be used in - * the result set for this statement. - * - * @return A new <code>CallableStatement</code>. - * - * @exception SQLException If an error occurs. - * - * @see CallableStatement - * @see ResultSet - */ -public abstract CallableStatement -prepareCall(String sql, int resultSetType, int resultSetConcurrency) - throws SQLException; - -/*************************************************************************/ - -/** - * This method converts the specified generic SQL statement into the - * native grammer of the database this object is connected to. - * - * @param The JDBC generic SQL statement. - * - * @return The native SQL statement. - * - * @exception SQLException If an error occurs. - */ -public abstract String -nativeSQL(String sql) throws SQLException; - -/*************************************************************************/ - -/** - * This method tests whether or not auto commit mode is currently enabled. - * In auto commit mode, every SQL statement is committed its own transaction. - * Otherwise a transaction must be explicitly committed or rolled back. - * - * @return <code>true</code> if auto commit mode is enabled, - * <code>false</code> otherwise. - * - * @exception SQLException If an error occurs. - * - * @see commit - * @see rollback - */ -public abstract boolean -getAutoCommit() throws SQLException; - -/*************************************************************************/ - -/** - * This method turns auto commit mode on or off. In auto commit mode, - * every SQL statement is committed its own transaction. Otherwise a - * transaction must be explicitly committed or rolled back. - * - * @param autoCommit <code>true</code> to enable auto commit mode, - * <code>false</code> to disable it. - * - * @exception SQLException If an error occurs. - * - * @see commit - * @see rollback - */ -public abstract void -setAutoCommit(boolean autoCommit) throws SQLException; - -/*************************************************************************/ - -/** + /** + * This transaction isolation level indicates that transactions are not + * supported. + */ + public static final int TRANSACTION_NONE = 0; + + /** + * This transaction isolation level indicates that one transaction can + * read modifications by other transactions before the other transactions + * have committed their changes. This could result in invalid reads. + */ + public static final int TRANSACTION_READ_UNCOMMITTED = 1; + + /** + * This transaction isolation leve indicates that only committed data from + * other transactions will be read. If a transaction reads a row, then + * another transaction commits a change to that row, the first transaction + * would retrieve the changed row on subsequent reads of the same row. + */ + public static final int TRANSACTION_READ_COMMITTED = 2; + + /** + * This transaction isolation level indicates that only committed data from + * other transactions will be read. It also ensures that data read from + * a row will not be different on a subsequent read even if another + * transaction commits a change. + */ + public static final int TRANSACTION_REPEATABLE_READ = 4; + + /** + * This transaction isolation level indicates that only committed data from + * other transactions will be read. It also ensures that data read from + * a row will not be different on a subsequent read even if another + * transaction commits a change. Additionally, rows modified by other + * transactions will not affect the result set returned during subsequent + * executions of the same WHERE clause in this transaction. + */ + public static final int TRANSACTION_SERIALIZABLE = 8; + + /** + * This method creates a new SQL statement. The default result set type + * and concurrency will be used. + * + * @return A new <code>Statement</code> object. + * @exception SQLException If an error occurs. + * @see Statement + */ + public Statement createStatement() throws SQLException; + + /** + * This method creates a new <code>PreparedStatement</code> for the specified + * SQL string. This method is designed for use with parameterized + * statements. The default result set type and concurrency will be used. + * + * @param The SQL statement to use in creating this + * <code>PreparedStatement</code>. + * @return A new <code>PreparedStatement</code>. + * @exception SQLException If an error occurs. + * @see PreparedStatement + */ + public PreparedStatement prepareStatement(String sql) throws SQLException; + + /** + * This method creates a new <code>CallableStatement</code> for the + * specified SQL string. Thie method is designed to be used with + * stored procedures. The default result set type and concurrency + * will be used. + * + * @param The SQL statement to use in creating this + * <code>CallableStatement</code>. + * @return A new <code>CallableStatement</code>. + * @exception SQLException If an error occurs. + * @see CallableStatement + */ + public CallableStatement prepareCall(String sql) throws SQLException; + + /** + * This method converts the specified generic SQL statement into the + * native grammer of the database this object is connected to. + * + * @param The JDBC generic SQL statement. + * @return The native SQL statement. + * @exception SQLException If an error occurs. + */ + public String nativeSQL(String sql) throws SQLException; + + /** + * This method turns auto commit mode on or off. In auto commit mode, + * every SQL statement is committed its own transaction. Otherwise a + * transaction must be explicitly committed or rolled back. + * + * @param autoCommit <code>true</code> to enable auto commit mode, + * <code>false</code> to disable it. + * @exception SQLException If an error occurs. + * @see commit + * @see rollback + */ + public void setAutoCommit(boolean autoCommit) throws SQLException; + + /** + * This method tests whether or not auto commit mode is currently enabled. + * In auto commit mode, every SQL statement is committed its own transaction. + * Otherwise a transaction must be explicitly committed or rolled back. + * + * @return <code>true</code> if auto commit mode is enabled, + * <code>false</code> otherwise. + * + * @exception SQLException If an error occurs. + * + * @see commit + * @see rollback + */ + public boolean getAutoCommit() throws SQLException; + + /** * This method commits any SQL statements executed on this connection since * the last commit or rollback. * * @exception SQLException If an error occurs. */ -public abstract void -commit() throws SQLException; - -/*************************************************************************/ - -/** - * This method rolls back any SQL statements executed on this connection - * since the last commit or rollback. - * - * @exception SQLException If an error occurs. - */ -public abstract void -rollback() throws SQLException; - -/*************************************************************************/ - -/** - * This method immediately closes this database connection. - * - * @exception SQLException If an error occurs. - */ -public abstract void -close() throws SQLException; - -/*************************************************************************/ - -/** - * This method tests whether or not this connection has been closed. - * - * @return <code>true</code> if the connection is closed, <code>false</code> - * otherwise. - * - * @exception SQLException If an error occurs. - */ -public abstract boolean -isClosed() throws SQLException; - -/*************************************************************************/ - -/** - * This method returns the meta data for this database connection. - * - * @return The meta data for this database. - * - * @exception SQLException If an error occurs. - * - * @see DatabaseMetaData - */ -public abstract DatabaseMetaData -getMetaData() throws SQLException; - -/*************************************************************************/ - -/** - * This method tests whether or not this connection is in read only mode. - * - * @return <code>true</code> if the connection is read only <code>false</code> - * otherwise. - * - * @exception SQLException If an error occurs. - */ -public abstract boolean -isReadOnly() throws SQLException; - -/*************************************************************************/ - -/** - * This method turns read only mode on or off. It may not be called while - * a transaction is in progress. - * - * @param readOnly <code>true</code> if this connection is read only, - * <code>false</code> otherwise. - * - * @exception SQLException If an error occurs. - */ -public abstract void -setReadOnly(boolean readOnly) throws SQLException; - -/*************************************************************************/ - -/** - * This method returns the name of the catalog in use by this connection, - * if any. - * - * @return The name of the catalog, or <code>null</code> if one does not - * exist or catalogs are not supported by this database. - * - * @exception SQLException If an error occurs. - */ -public abstract String -getCatalog() throws SQLException; - -/*************************************************************************/ - -/** - * This method sets the name of the catalog in use by this connection. - * Note that this method does nothing if catalogs are not supported by - * this database. - * - * @param catalog The name of the catalog to use for this connection. - * - * @exception SQLException If an error occurs. - */ -public abstract void -setCatalog(String catalog) throws SQLException; - -/*************************************************************************/ - -/** - * This method returns the current transaction isolation mode. This will - * be one of the constants defined in this interface. - * - * @return The transaction isolation level. - * - * @exception SQLException If an error occurs. - */ -public abstract int -getTransactionIsolation() throws SQLException; - -/*************************************************************************/ - -/** - * This method sets the current transaction isolation mode. This must - * be one of the constants defined in this interface. - * - * @param level The transaction isolation level. - * - * @exception SQLException If an error occurs. - */ -public abstract void -setTransactionIsolation(int level) throws SQLException; - -/*************************************************************************/ - -/** - * This method returns the first warning that occurred on this connection, - * if any. If there were any subsequence warnings, they will be chained - * to the first one. - * - * @return The first <code>SQLWarning</code> that occurred, or - * <code>null</code> if there have been no warnings. - * - * @exception SQLException If an error occurs. - */ -public abstract SQLWarning -getWarnings() throws SQLException; - -/*************************************************************************/ - -/** - * This method clears all warnings that have occurred on this connection. - * - * @exception SQLException If an error occurs. - */ -public abstract void -clearWarnings() throws SQLException; - -/*************************************************************************/ - -/** - * This method returns the mapping of SQL types to Java classes - * currently in use by this connection. This mapping will have no - * entries unless they have been manually added. - * - * @return The SQL type to Java class mapping. - * - * @exception SQLException If an error occurs. - */ -public abstract Map -getTypeMap() throws SQLException; - -/*************************************************************************/ - -/** - * This method sets the mapping table for SQL types to Java classes. - * Any entries in this map override the defaults. - * - * @param map The new SQL mapping table. - * - * @exception SQLException If an error occurs. - */ -public abstract void -setTypeMap(Map map) throws SQLException; - -} // interface Connection - + public void commit() throws SQLException; + + /** + * This method rolls back any SQL statements executed on this connection + * since the last commit or rollback. + * + * @exception SQLException If an error occurs. + */ + public void rollback() throws SQLException; + + /** + * This method immediately closes this database connection. + * + * @exception SQLException If an error occurs. + */ + public void close() throws SQLException; + + /** + * This method tests whether or not this connection has been closed. + * + * @return <code>true</code> if the connection is closed, <code>false</code> + * otherwise. + * @exception SQLException If an error occurs. + */ + public boolean isClosed() throws SQLException; + + /** + * This method returns the meta data for this database connection. + * + * @return The meta data for this database. + * @exception SQLException If an error occurs. + * @see DatabaseMetaData + */ + public DatabaseMetaData getMetaData() throws SQLException; + + /** + * This method turns read only mode on or off. It may not be called while + * a transaction is in progress. + * + * @param readOnly <code>true</code> if this connection is read only, + * <code>false</code> otherwise. + * @exception SQLException If an error occurs. + */ + public void setReadOnly(boolean readOnly) throws SQLException; + + /** + * This method tests whether or not this connection is in read only mode. + * + * @return <code>true</code> if the connection is read only <code>false</code> + * otherwise. + * @exception SQLException If an error occurs. + */ + public boolean isReadOnly() throws SQLException; + + /** + * This method sets the name of the catalog in use by this connection. + * Note that this method does nothing if catalogs are not supported by + * this database. + * + * @param catalog The name of the catalog to use for this connection. + * @exception SQLException If an error occurs. + */ + public void setCatalog(String catalog) throws SQLException; + + /** + * This method returns the name of the catalog in use by this connection, + * if any. + * + * @return The name of the catalog, or <code>null</code> if one does not + * exist or catalogs are not supported by this database. + * @exception SQLException If an error occurs. + */ + public String getCatalog() throws SQLException; + + /** + * This method sets the current transaction isolation mode. This must + * be one of the constants defined in this interface. + * + * @param level The transaction isolation level. + * @exception SQLException If an error occurs. + */ + public void setTransactionIsolation(int level) throws SQLException; + + /** + * This method returns the current transaction isolation mode. This will + * be one of the constants defined in this interface. + * + * @return The transaction isolation level. + * @exception SQLException If an error occurs. + */ + public int getTransactionIsolation() throws SQLException; + + /** + * This method returns the first warning that occurred on this connection, + * if any. If there were any subsequence warnings, they will be chained + * to the first one. + * + * @return The first <code>SQLWarning</code> that occurred, or + * <code>null</code> if there have been no warnings. + * @exception SQLException If an error occurs. + */ + public SQLWarning getWarnings() throws SQLException; + + /** + * This method clears all warnings that have occurred on this connection. + * + * @exception SQLException If an error occurs. + */ + public void clearWarnings() throws SQLException; + + /** + * This method creates a new SQL statement with the specified type and + * concurrency. Valid values for these parameters are specified in the + * <code>ResultSet</code> class. + * + * @param resultSetType The type of result set to use for this statement. + * @param resultSetConcurrency. The type of concurrency to be used in + * the result set for this statement. + * @return A new <code>Statement</code> object. + * @exception SQLException If an error occurs. + * @see Statement + * @see ResultSet + */ + public Statement createStatement(int resultSetType, int resultSetConcurrency) + throws SQLException; + + /** + * This method creates a new <code>PreparedStatement</code> for the specified + * SQL string. This method is designed for use with parameterized + * statements. The specified result set type and concurrency will be used. + * Valid values for these parameters are specified in the + * <code>ResultSet</code> class. + * + * @param The SQL statement to use in creating this + * <code>PreparedStatement</code>. + * @param resultSetType The type of result set to use for this statement. + * @param resultSetConcurrency. The type of concurrency to be used in + * the result set for this statement. + * @return A new <code>PreparedStatement</code>. + * @exception SQLException If an error occurs. + * @see PreparedStatement + * @see ResultSet + */ + public PreparedStatement prepareStatement(String sql, int resultSetType, + int resultSetConcurrency) throws SQLException; + + /** + * This method creates a new <code>CallableStatement</code> for the + * specified SQL string. Thie method is designed to be used with + * stored procedures. The specified result set type and concurrency + * will be used. Valid values for these parameters are specified in the + * <code>ResultSet</code> class. + * + * @param The SQL statement to use in creating this + * <code>PreparedStatement</code>. + * @param resultSetType The type of result set to use for this statement. + * @param resultSetConcurrency. The type of concurrency to be used in + * the result set for this statement. + * @return A new <code>CallableStatement</code>. + * @exception SQLException If an error occurs. + * @see CallableStatement + * @see ResultSet + */ + public CallableStatement prepareCall(String sql, int resultSetType, int + resultSetConcurrency) throws SQLException; + + /** + * This method returns the mapping of SQL types to Java classes + * currently in use by this connection. This mapping will have no + * entries unless they have been manually added. + * + * @return The SQL type to Java class mapping. + * @exception SQLException If an error occurs. + */ + public Map getTypeMap() throws SQLException; + + /** + * This method sets the mapping table for SQL types to Java classes. + * Any entries in this map override the defaults. + * + * @param map The new SQL mapping table. + * @exception SQLException If an error occurs. + */ + public void setTypeMap(Map map) throws SQLException; + + /** + * @since 1.4 + */ + public void setHoldability(int holdability) throws SQLException; + + /** + * @since 1.4 + */ + public int getHoldability() throws SQLException; + + /** + * @since 1.4 + */ + public Savepoint setSavepoint() throws SQLException; + + /** + * @since 1.4 + */ + public Savepoint setSavepoint(String name) throws SQLException; + + /** + * @since 1.4 + */ + public void rollback(Savepoint savepoint) throws SQLException; + + /** + * @since 1.4 + */ + public void releaseSavepoint(Savepoint savepoint) throws SQLException; + + /** + * @since 1.4 + */ + public Statement createStatement(int resultSetType, int + resultSetConcurrency, int resultSetHoldability) throws SQLException; + + /** + * @since 1.4 + */ + public PreparedStatement prepareStatement(String sql, int resultSetType, int + resultSetConcurrency, int resultSetHoldability) throws SQLException; + + /** + * @since 1.4 + */ + public CallableStatement prepareCall(String sql, int resultSetType, int + resultSetConcurrency, int resultSetHoldability) throws SQLException; + + /** + * @since 1.4 + */ + public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) + throws SQLException; + + /** + * @since 1.4 + */ + public PreparedStatement prepareStatement(String sql, int[] columnIndexes) + throws SQLException; + + /** + * @since 1.4 + */ + public PreparedStatement prepareStatement(String sql, String[] columnNames) + throws SQLException; +} |