ModSQL
Class Connection

java.lang.Object
  |
  +--ModSQL.Connection

All Implemented Interfaces:

Connection

public class Connection

extends Object

implements Connection

A Connection represents a session with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or database changes will not be saved.

Author:

chris.studholme@utoronto.ca

See Also:

PreparedStatement, ResultSet, DatabaseMetaData

Field Summary

protected DatabaseManager

tablemanager DatabaseManager to use for looking up tables.

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Constructor Summary

Connection()
Constructor.

Method Summary

void	clearWarnings() After this call, getWarnings returns null until a new warning is reported for this Connection.
void	close() In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.
void	commit() Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.
Statement	createStatement() SQL statements without parameters are normally executed using Statement objects.
Statement	createStatement(int resultSetType, int resultSetConcurrency) Same as createStatement() above, but allows the default result set type and result set concurrency type to be overridden.
boolean	getAutoCommit() Get the current auto-commit state.
String	getCatalog() Return the Connection's current catalog name.
DatabaseMetaData	getMetaData() A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc.
int	getTransactionIsolation() Get this Connection's current transaction isolation mode.
Map	getTypeMap() Not implemented.
SQLWarning	getWarnings() The first warning reported by calls on this Connection is returned.
boolean	isClosed() Tests to see if a Connection is closed.
boolean	isReadOnly() Tests to see if the connection is in read-only mode.
String	nativeSQL(String sql) A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.
CallableStatement	prepareCall(String sql) A SQL stored procedure call statement is handled by creating a CallableStatement for it.
CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency) Same as prepareCall() above, but allows the default result set type and result set concurrency type to be overridden.
PreparedStatement	prepareStatement(String sql) A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object.
PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency) Same as prepareStatement() above, but allows the default result set type and result set concurrency type to be overridden.
void	rollback() Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection.
void	setAutoCommit(boolean autoCommit) If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions.
void	setCatalog(String catalog) A sub-space of this Connection's database may be selected by setting a catalog name.
void	setReadOnly(boolean readOnly) You can put a connection in read-only mode as a hint to enable database optimizations.
void	setTransactionIsolation(int level) You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.
void	setTypeMap(Map map) Not implemented.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

tablemanager

protected DatabaseManager tablemanager

DatabaseManager to use for looking up tables.

Constructor Detail

Connection

public Connection()

Constructor. Uses MetaManager as default DatabaseManager.

Method Detail

createStatement

public Statement createStatement()
                          throws SQLException

SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it is more efficient to use a PreparedStatement

Specified by:

createStatement in interface Connection

Returns:

a new Statement object

Throws:

SQLException - if a database-access error occurs.

prepareStatement

public PreparedStatement prepareStatement(String sql)
                                   throws SQLException

A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Specified by:

prepareStatement in interface Connection

Parameters:

sql - a SQL statement that may contain one or more '?' IN parameter placeholders

Returns:

a new PreparedStatement object containing the pre-compiled statement

Throws:

SQLException - if a database-access error occurs.

prepareCall

public CallableStatement prepareCall(String sql)
                              throws SQLException

A SQL stored procedure call statement is handled by creating a CallableStatement for it. The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing it.

Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the prepareCall is done; others may wait until the CallableStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Specified by:

prepareCall in interface Connection

Parameters:

sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.

Returns:

a new CallableStatement object containing the pre-compiled SQL statement

Throws:

SQLException - if a database-access error occurs.

nativeSQL

public String nativeSQL(String sql)
                 throws SQLException

A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.

Specified by:

nativeSQL in interface Connection

Parameters:

sql - a SQL statement that may contain one or more '?' parameter placeholders

Returns:

the native form of this statement

Throws:

SQLException - if a database-access error occurs.

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws SQLException

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in auto-commit mode. The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output param values have been retrieved.

Specified by:

setAutoCommit in interface Connection

Parameters:

autoCommit - true enables auto-commit; false disables auto-commit.

Throws:

SQLException - if a database-access error occurs.

getAutoCommit

public boolean getAutoCommit()
                      throws SQLException

Get the current auto-commit state.

Specified by:

getAutoCommit in interface Connection

Returns:

Current state of auto-commit mode.

Throws:

SQLException - if a database-access error occurs.

See Also:

setAutoCommit(boolean)

commit

public void commit()
            throws SQLException

Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Specified by:

commit in interface Connection

Throws:

SQLException - if a database-access error occurs.

See Also:

setAutoCommit(boolean)

rollback

public void rollback()
              throws SQLException

Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Specified by:

rollback in interface Connection

Throws:

SQLException - if a database-access error occurs.

See Also:

setAutoCommit(boolean)

close

public void close()
           throws SQLException

In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.

Note: A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection.

Specified by:

close in interface Connection

Throws:

SQLException - if a database-access error occurs.

isClosed

public boolean isClosed()
                 throws SQLException

Tests to see if a Connection is closed.

Specified by:

isClosed in interface Connection

Returns:

true if the connection is closed; false if it's still open

Throws:

SQLException - if a database-access error occurs.

getMetaData

public DatabaseMetaData getMetaData()
                             throws SQLException

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is made available through a DatabaseMetaData object.

Specified by:

getMetaData in interface Connection

Returns:

a DatabaseMetaData object for this Connection

Throws:

SQLException - if a database-access error occurs.

setReadOnly

public void setReadOnly(boolean readOnly)
                 throws SQLException

You can put a connection in read-only mode as a hint to enable database optimizations.

Note: setReadOnly cannot be called while in the middle of a transaction.

Specified by:

setReadOnly in interface Connection

Parameters:

readOnly - true enables read-only mode; false disables read-only mode.

Throws:

SQLException - if a database-access error occurs.

isReadOnly

public boolean isReadOnly()
                   throws SQLException

Tests to see if the connection is in read-only mode.

Specified by:

isReadOnly in interface Connection

Returns:

true if connection is read-only

Throws:

SQLException - if a database-access error occurs.

setCatalog

public void setCatalog(String catalog)
                throws SQLException

A sub-space of this Connection's database may be selected by setting a catalog name. If the driver does not support catalogs it will silently ignore this request.

Specified by:

setCatalog in interface Connection

Throws:

SQLException - if a database-access error occurs.

getCatalog

public String getCatalog()
                  throws SQLException

Return the Connection's current catalog name.

Specified by:

getCatalog in interface Connection

Returns:

the current catalog name or null

Throws:

SQLException - if a database-access error occurs.

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws SQLException

You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.

Note: setTransactionIsolation cannot be called while in the middle of a transaction.

Specified by:

setTransactionIsolation in interface Connection

Parameters:

level - one of the TRANSACTION_* isolation values with the exception of TRANSACTION_NONE; some databases may not support other values

Throws:

SQLException - if a database-access error occurs.

See Also:

DatabaseMetaData.supportsTransactionIsolationLevel(int)

getTransactionIsolation

public int getTransactionIsolation()
                            throws SQLException

Get this Connection's current transaction isolation mode.

Specified by:

getTransactionIsolation in interface Connection

Returns:

the current TRANSACTION_* mode value

Throws:

SQLException - if a database-access error occurs.

getWarnings

public SQLWarning getWarnings()
                       throws SQLException

The first warning reported by calls on this Connection is returned.

Note: Subsequent warnings will be chained to this SQLWarning.

Specified by:

getWarnings in interface Connection

Returns:

the first SQLWarning or null

Throws:

SQLException - if a database-access error occurs.

clearWarnings

public void clearWarnings()
                   throws SQLException

After this call, getWarnings returns null until a new warning is reported for this Connection.

Specified by:

clearWarnings in interface Connection

Throws:

SQLException - if a database-access error occurs.

createStatement

public Statement createStatement(int resultSetType,
                                 int resultSetConcurrency)
                          throws SQLException

Same as createStatement() above, but allows the default result set type and result set concurrency type to be overridden.

Specified by:

createStatement in interface Connection

Parameters:

resultSetType - a result set type, see ResultSet.TYPE_XXX

resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX

Returns:

a new Statement object

Throws:

SQLException - if a database-access error occurs.

prepareStatement

public PreparedStatement prepareStatement(String sql,
                                          int resultSetType,
                                          int resultSetConcurrency)
                                   throws SQLException

Same as prepareStatement() above, but allows the default result set type and result set concurrency type to be overridden.

Specified by:

prepareStatement in interface Connection

Parameters:

resultSetType - a result set type, see ResultSet.TYPE_XXX

resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX

Returns:

a new PreparedStatement object containing the pre-compiled SQL statement

Throws:

SQLException - if a database-access error occurs.

prepareCall

public CallableStatement prepareCall(String sql,
                                     int resultSetType,
                                     int resultSetConcurrency)
                              throws SQLException

Same as prepareCall() above, but allows the default result set type and result set concurrency type to be overridden.

Specified by:

prepareCall in interface Connection

Parameters:

resultSetType - a result set type, see ResultSet.TYPE_XXX

resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX

Returns:

a new CallableStatement object containing the pre-compiled SQL statement

Throws:

SQLException - if a database-access error occurs.

getTypeMap

public Map getTypeMap()
               throws SQLException

Not implemented.

Specified by:

getTypeMap in interface Connection

setTypeMap

public void setTypeMap(Map map)
                throws SQLException

Not implemented.

Specified by:

setTypeMap in interface Connection