com.nec.tdd.tools.dbMapper
Interface DBConnection

All Known Implementing Classes:
DBConnectionImpl

public interface DBConnection

A DBConnection object is a connection object with additional features of maintaining cache of frequently used (prepared, callable) statements for the connection.

DBConnection also restricts access to underlying java.sql.Connection methods (i.e. close, prepare Call etc). This is done to give full control of DBConnection object lifecycle to the connection manager which created this DBConnection.

Recommendation: Cached prepared and callable statements for this database connections can be indexed/keyed as following :

    [User class name as defined in mapping file] + "_" + [Corresponding table
    name from mapping file] + "_" + [operation_type i.e. create, delete, find]
 


Method Summary
 void addCallableStatement(java.lang.String name, java.lang.String sql)
          Prepare and add a callable statement to this DB connection.
 void addCallableStatement(java.lang.String name, java.lang.String sql, boolean isOverWritable)
          Prepare and add a callable statement to this DB connection.
 void addPreparedStatement(java.lang.String name, java.lang.String sql)
          Prepare and add a prepared statement to this DB connection.
 void addPreparedStatement(java.lang.String name, java.lang.String sql, boolean isOverWritable)
          Prepare and add a prepared statement to this DB connection.
 void commit()
          Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.
 boolean getAutoCommit()
          Get the current auto-commit state.
 java.sql.CallableStatement getCallableStatement(java.lang.String name)
          Get a cached callable statement associated with this DB connection.
 java.sql.DatabaseMetaData getMetaData()
          Gets the metadata regarding this connection's database.
 java.sql.PreparedStatement getPreparedStatement(java.lang.String name)
          Get a cached prepared statement associated with this DB connection.
 java.sql.Statement getStatement()
          Get statement associated with this DB connection.
 boolean isClosed()
          Tests to see if a Connection is closed.
 boolean isReadOnly()
          Tests to see if the connection is in read-only mode.
 java.sql.CallableStatement makeCallableStatement(java.lang.String sql)
          Make/create a callable statement for this DB connection.
 java.sql.PreparedStatement makePreparedStatement(java.lang.String sql)
          Make/create a prepared statement for this DB connection.
 void rollback()
          Drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection.
 void setAutoCommit(boolean isEnabled)
          Sets this connection's auto-commit state.
 void setReadOnly(boolean isReadOnly)
          Puts this connection in read-only mode as a hint to enable database optimizations.
 

Method Detail

getStatement

public java.sql.Statement getStatement()
Get statement associated with this DB connection. Lifecycle of statement will be managed by DBConnection. It is created during object construction and closed when DBConnection is destroyed. So external routines SHOULD NOT close the statement.
Returns:
the statement associated with this DB connection.

getPreparedStatement

public java.sql.PreparedStatement getPreparedStatement(java.lang.String name)
Get a cached prepared statement associated with this DB connection. Lifecycle of prepared statement will be managed by DBConnection. So external routines should not close the prepared statement.
Parameters:
name - key whose associated cached prepared statement is to be returned (provided during addPreparedStatement).
Returns:
the prepared statement to which name is mapped. Returns null if no mapping for the name.

makePreparedStatement

public java.sql.PreparedStatement makePreparedStatement(java.lang.String sql)
                                                 throws java.sql.SQLException
Make/create a prepared statement for this DB connection. Returned statement is not cached and its lifecycle should be managed by calling method. User should close the prepared statement when done with it.
Parameters:
sql - a SQL statement that may contain one or more '?' IN parameter placeholders
Returns:
a new PreparedStatement object containing the pre-compiled sql statement
Throws:
java.sql.SQLException - if a database access error occurs.

addPreparedStatement

public void addPreparedStatement(java.lang.String name,
                                 java.lang.String sql,
                                 boolean isOverWritable)
                          throws java.sql.SQLException
Prepare and add a prepared statement to this DB connection. If an entry with same name exists, isOverWritable parameter determines whether or not to overwrite the cached entry.
Parameters:
name - key with which the prepared statement is to be associated
sql - a SQL statement that may contain one or more '?' IN parameter placeholders
isOverWritable - specifies whether or not to overwrite cached entry.
Throws:
java.sql.SQLException - if a database access error occurs.
See Also:
addPreparedStatement(String,String)

addPreparedStatement

public void addPreparedStatement(java.lang.String name,
                                 java.lang.String sql)
                          throws java.sql.SQLException
Prepare and add a prepared statement to this DB connection. If an entry with same name exists, it will be overwritten.
Parameters:
name - key with which the prepared statement is to be associated
sql - a SQL statement that may contain one or more '?' IN parameter placeholders
Throws:
java.sql.SQLException - if a database access error occurs.
See Also:
addPreparedStatement(String,String,boolean)

getCallableStatement

public java.sql.CallableStatement getCallableStatement(java.lang.String name)
Get a cached callable statement associated with this DB connection. Lifecycle of callable statement will be managed by DBConnection. So external routines should not close the callable statement.
Parameters:
name - key whose associated cached callable statement is to be returned (provided during addCallableStatement).
Returns:
the callable statement to which name is mapped. Returns null if no mapping for the name.

makeCallableStatement

public java.sql.CallableStatement makeCallableStatement(java.lang.String sql)
                                                 throws java.sql.SQLException
Make/create a callable statement for this DB connection. Returned statement is not cached and its lifecycle should be managed by calling method. User should close the callable statement when done with it.
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:
java.sql.SQLException - if a database access error occurs.

addCallableStatement

public void addCallableStatement(java.lang.String name,
                                 java.lang.String sql,
                                 boolean isOverWritable)
                          throws java.sql.SQLException
Prepare and add a callable statement to this DB connection. If an entry with same name exists, isOverWritable parameter determines whether or not to overwrite the cached entry.
Parameters:
name - key with which the callable statement is to be associated
sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.
isOverWritable - specifies whether or not to overwrite cached entry.
Throws:
java.sql.SQLException - if a database access error occurs.
See Also:
addCallableStatement(String,String)

addCallableStatement

public void addCallableStatement(java.lang.String name,
                                 java.lang.String sql)
                          throws java.sql.SQLException
Prepare and add a callable statement to this DB connection. If an entry with same name exists, it will be overwritten.
Parameters:
name - key with which the callable statement is to be associated
sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.
Throws:
java.sql.SQLException - if a database access error occurs.
See Also:
addCallableStatement(String,String,boolean)

getAutoCommit

public boolean getAutoCommit()
                      throws java.sql.SQLException
Get the current auto-commit state. By default a new connection will be in auto commit mode.
Returns:
the current state of auto-commit mode
Throws:
java.sql.SQLException - if a database access error occurs.

setAutoCommit

public void setAutoCommit(boolean isEnabled)
                   throws java.sql.SQLException
Sets this connection's auto-commit state. For more detail refer to java.sql.Connection interface documentation.
Parameters:
isEnabled - true enables auto-commit; false disables auto-commit.
Throws:
java.sql.SQLException - if a database access error occurs.

commit

public void commit()
            throws java.sql.SQLException
Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should be used only when auto-commit mode has been disabled.
Throws:
java.sql.SQLException - if a database access error occurs.

rollback

public void rollback()
              throws java.sql.SQLException
Drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection. This method should be used only when auto- commit has been disabled.
Throws:
java.sql.SQLException - if a database access error occurs.

getMetaData

public java.sql.DatabaseMetaData getMetaData()
                                      throws java.sql.SQLException
Gets the metadata regarding this connection's database.
Returns:
a DatabaseMetaData object for this Connection
Throws:
java.sql.SQLException - if a database access error occurs.

isReadOnly

public boolean isReadOnly()
                   throws java.sql.SQLException
Tests to see if the connection is in read-only mode.
Returns:
true if connection is read-only and false otherwise
Throws:
java.sql.SQLException - if a database access error occurs.

setReadOnly

public void setReadOnly(boolean isReadOnly)
                 throws java.sql.SQLException
Puts this connection in read-only mode as a hint to enable database optimizations.

Note: This method cannot be called while in the middle of a transaction. Calling routines are responsible to to check the connection type before using it.

Parameters:
isReadOnly - true enables read-only mode; false disables read-only mode.
Throws:
java.sql.SQLException - if a database access error occurs.

isClosed

public boolean isClosed()
                 throws java.sql.SQLException
Tests to see if a Connection is closed.
Returns:
true if the connection is closed; false if it's still open.
Throws:
java.sql.SQLException - if a database access error occurs.