EAF 7.4 API

com.lutris.appserver.server.sql
Interface DBConnection


public interface DBConnection

This interface defines a database connection.

Since:
LBS1.8
Version:
$Revision: 1.1 $
Author:
Paul Morgan

Method Summary
 void allocate()
          Method called when this connection object is allocated from the connection allocator.
 void close()
          Close this connection.
 void commit()
          Commit a transaction.
 boolean execute(java.lang.String sql)
          Execute a SQL statement that does not return a resultset.
 java.sql.ResultSet executeQuery(java.sql.PreparedStatement preparedStmt, java.lang.String msg)
          Execute a prepared query statement.
 java.sql.ResultSet executeQuery(java.lang.String sql)
          Execute a SQL query statement.
 int executeUpdate(java.sql.PreparedStatement preparedStmt, java.lang.String msg)
          Execute a prepared update statement.
 int executeUpdate(java.lang.String sql)
          Execute a SQL update statement.
 java.sql.Connection getConnection()
          Get the underlying Connection object.
 java.lang.String getDatabaseName()
           
 int getGeneration()
          Get the generation number specified when the connection was created.
 java.lang.String getUrl()
          Get the database URL.
 java.lang.String getUser()
          Get the database user name.
 boolean handleException(java.sql.SQLException sqlExcept)
          Check if a connection is valid after an SQL exception is thrown.
 void incrRequestCount()
          Increment the count of the number of requests against this connection.
 boolean isMarkedForDrop()
           
 java.sql.CallableStatement prepareCall(java.lang.String sql)
          Creates a CallableStatement object for calling database stored procedures.
 java.sql.PreparedStatement prepareStatement(java.lang.String sql)
          Get a prepared statement given an SQL string.
 void release()
          Return this connection to its allocator.
 void reset()
          Closes down all query-specific resources.
 void rollback()
          Rollback a transaction.
 void setAutoCommit(boolean on)
          Autocommit on/off.
 void validate()
          Validates this connection.
 void warningCheck(java.sql.ResultSet resultSet)
          Check for warnings in a result set.
 

Method Detail

validate

void validate()
              throws java.sql.SQLException
Validates this connection. Check to see that it is not closed and has been properly allocated.

Throws:
java.sql.SQLException - If it is not valid.

reset

void reset()
           throws java.sql.SQLException
Closes down all query-specific resources.

Throws:
java.sql.SQLException - If a database error occurs.

prepareStatement

java.sql.PreparedStatement prepareStatement(java.lang.String sql)
                                            throws java.sql.SQLException
Get a prepared statement given an SQL string. If the statement is cached, return that statement, otherwise prepare and save in the cache.

Parameters:
sql - The SQL statement to prepared.
Returns:
The prepared statement, which is associated only with this connection and must not be used once the connection is released.
Throws:
java.sql.SQLException - If a SQL error occured compiling the statement.

prepareCall

java.sql.CallableStatement prepareCall(java.lang.String sql)
                                       throws java.sql.SQLException
Creates a CallableStatement object for calling database stored procedures. Refer to jdk api refernece.

Parameters:
sql - The SQL statement to be called.
Returns:
a new CallableStatement object containing the pre-compiled SQL statement.
Throws:
java.sql.SQLException - If a database access error occurs statement.

executeQuery

java.sql.ResultSet executeQuery(java.sql.PreparedStatement preparedStmt,
                                java.lang.String msg)
                                throws java.sql.SQLException
Execute a prepared query statement. Once the query has completed, reset() should be called.

Parameters:
preparedStmt - The statement to execute.
msg - for logging/debug purposes
Returns:
Query result set, do not call close, use reset(),
Throws:
java.sql.SQLException - If a SQL error occured executing the statement.

executeQuery

java.sql.ResultSet executeQuery(java.lang.String sql)
                                throws java.sql.SQLException
Execute a SQL query statement. This is a wrapper that adds logging. Once the query has completed, reset() should be called.

Parameters:
sql - The SQL query statement
Returns:
Query result set, do not call close, use reset(),
Throws:
java.sql.SQLException - If a SQL error occured executing the statement.

executeUpdate

int executeUpdate(java.lang.String sql)
                  throws java.sql.SQLException
Execute a SQL update statement. This is a wrapper that adds logging. Once the update has completed, reset() should be called.

Parameters:
sql - The SQL query statement
Returns:
Either the row count for UPDATE, INSERT, DELETE or 0 for SQL statements that return nothing.
Throws:
java.sql.SQLException - If a SQL error occured executing the update.

executeUpdate

int executeUpdate(java.sql.PreparedStatement preparedStmt,
                  java.lang.String msg)
                  throws java.sql.SQLException
Execute a prepared update statement. Once the update has completed, reset() should be called.

Parameters:
preparedStmt - The statement to execute.
msg - for logging/debug purposes
Returns:
Either the row count for UPDATE, INSERT, DELETE or 0 for SQL statements that return nothing.
Throws:
java.sql.SQLException - If a SQL error occured executing the statement.

execute

boolean execute(java.lang.String sql)
                throws java.sql.SQLException
Execute a SQL statement that does not return a resultset. This is a wrapper that adds logging. Once the query has completed, reset() should be called.

Parameters:
sql - The SQL query statement
Returns:
True if the next result is a ResultSet; false if it is an update count or there are no more results.
Throws:
java.sql.SQLException - If a SQL error occured executing the statement.

warningCheck

void warningCheck(java.sql.ResultSet resultSet)
                  throws java.sql.SQLException
Check for warnings in a result set.

Parameters:
resultSet - The result set to check for warnings.
Throws:
java.sql.SQLException - If a SQL error occured compiling the statement.

release

void release()
Return this connection to its allocator. This object should not be used after calling this function.


handleException

boolean handleException(java.sql.SQLException sqlExcept)
Check if a connection is valid after an SQL exception is thrown. If it is not usable, then the connection is dropped from the connection allocator and closed. The connection is then no longer usable.

Parameters:
sqlExcept - the SQL exception that occured.
Returns:
true if the exception does not affect this connection object. False otherwise - in which case this connection object is no longer usable.

commit

void commit()
            throws java.sql.SQLException
Commit a transaction.

Throws:
java.sql.SQLException - If a database access error occurs.

setAutoCommit

void setAutoCommit(boolean on)
                   throws java.sql.SQLException
Autocommit on/off.

Parameters:
on - false to disable auto commit mode. True to enable.
Throws:
java.sql.SQLException - if a database access error occurs.

rollback

void rollback()
              throws java.sql.SQLException
Rollback a transaction. Should only be used when auto-commit mode has been disabled.

Throws:
java.sql.SQLException - if a database access error occurs.

allocate

void allocate()
              throws java.sql.SQLException
Method called when this connection object is allocated from the connection allocator.

Throws:
java.sql.SQLException - if reset had no been called on the previous operation.

close

void close()
Close this connection. Use by the connection allocator when this object is no longer used. Errors are ignored.


getGeneration

int getGeneration()
Get the generation number specified when the connection was created.

Returns:
The generation number.

incrRequestCount

void incrRequestCount()
Increment the count of the number of requests against this connection.


getUrl

java.lang.String getUrl()
Get the database URL.

Returns:
The database URL.

getUser

java.lang.String getUser()
Get the database user name. Normally user for error messages.

Returns:
The database user name.

getConnection

java.sql.Connection getConnection()
Get the underlying Connection object. Use with extreme caution.

Returns:
the connection object

isMarkedForDrop

boolean isMarkedForDrop()
Returns:
true if this connection is marked to be dropped out of the connection pool and closed.

getDatabaseName

java.lang.String getDatabaseName()
Returns:
database name of current connection

EAF 7.4 API