: Class Connection

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD