Module is.codion.common.db

Package is.codion.common.db.connection

Interface DatabaseConnection

All Superinterfaces:

AutoCloseable

public interface DatabaseConnection
extends AutoCloseable

Manages a Connection instance, providing basic transaction control. A factory class for DatabaseConnection instances.

Field Summary

Fields

Modifier and Type	Field	Description
static String	SQL_STATE_NO_DATA	SQLException state indicating that a query did not return a result

Method Summary

Modifier and Type	Method	Description
void	beginTransaction()	Begins a transaction on this connection, to end the transaction use commitTransaction() or rollbackTransaction().
void	close()	Performs a rollback and disconnects this connection.
void	commit()	Performs a commit
void	commitTransaction()	Performs a commit and ends the current transaction
Database	database()
static DatabaseConnection	databaseConnection(Database database, User user)	Constructs a new DatabaseConnection instance, based on the given Database and User
static DatabaseConnection	databaseConnection(Database database, Connection connection)	Constructs a new DatabaseConnection instance, based on the given Connection object.
Connection	getConnection()	Returns the underlying connection object, null in case this connection has been closed.
MethodLogger	getMethodLogger()
boolean	isConnected()
boolean	isTransactionOpen()
void	rollback()	Performs a rollback
void	rollbackTransaction()	Performs a rollback and ends the current transaction
int	selectInteger(String sql)	Selects a single integer value using the given query.
long	selectLong(String sql)	Selects a single long value using the given query.
void	setConnection(Connection connection)	Sets the internal connection to use, note that no validation or transaction checking is performed on the connection and auto-commit is assumed to be disabled.
void	setMethodLogger(MethodLogger methodLogger)
User	user()

Field Detail

SQL_STATE_NO_DATA

static final String SQL_STATE_NO_DATA

SQLException state indicating that a query did not return a result

See Also:

Constant Field Values

Method Detail

isConnected

boolean isConnected()

Returns:

true if the connection has been established and is valid

getConnection

Connection getConnection()

Returns the underlying connection object, null in case this connection has been closed. Use isConnected() to verify that the connection is not null and valid.

Returns:

the underlying connection object, null in case this connection has been closed

setConnection

void setConnection(Connection connection)

Sets the internal connection to use, note that no validation or transaction checking is performed on the connection and auto-commit is assumed to be disabled. The connection is simply used 'as is'. Note that setting the connection to null causes all methods requiring it to throw a IllegalStateException until a non-null connection is set.

Parameters:

connection - the JDBC connection

selectInteger

int selectInteger(String sql)
           throws SQLException

Selects a single integer value using the given query.

Parameters:

sql - the query must select at least a single number column, any other subsequent columns are ignored

Returns:

the first column from the first record in the result as an integer

Throws:

SQLException - if anything goes wrong during the execution, or no results from query with SQLException.getSQLState() as SQL_STATE_NO_DATA

selectLong

long selectLong(String sql)
         throws SQLException

Selects a single long value using the given query.

Parameters:

sql - the query must select at least a single number column, any other subsequent columns are ignored

Returns:

the first column from the first record in the result as a long

Throws:

SQLException - if anything goes wrong during the execution, or no results from query with SQLException.getSQLState() as SQL_STATE_NO_DATA

beginTransaction

void beginTransaction()

Begins a transaction on this connection, to end the transaction use commitTransaction() or rollbackTransaction().

Throws:

IllegalStateException - in case a transaction is already open

isTransactionOpen

boolean isTransactionOpen()

Returns:

true if a transaction is open

commitTransaction

void commitTransaction()

Performs a commit and ends the current transaction

Throws:

IllegalStateException - in case transaction is not open

rollbackTransaction

void rollbackTransaction()

Performs a rollback and ends the current transaction

Throws:

IllegalStateException - in case transaction is not open

commit

void commit()
     throws SQLException

Performs a commit

Throws:

SQLException - thrown if anything goes wrong during the execution

IllegalStateException - in case a transaction is open

rollback

void rollback()
       throws SQLException

Performs a rollback

Throws:

SQLException - thrown if anything goes wrong during the execution

IllegalStateException - in case a transaction is open

close

void close()

Performs a rollback and disconnects this connection. The only way to resurrect a closed connection is by using setConnection(Connection). Calling this method renders this connection unusable, subsequent calls to methods using the underlying connection result in a IllegalStateException being thrown, that is, until a new Connection is set via setConnection(Connection).

Specified by:

close in interface AutoCloseable

user

User user()

Returns:

the connection user

database

Database database()

Returns:

the database implementation this connection is based on

setMethodLogger

void setMethodLogger(MethodLogger methodLogger)

Parameters:

methodLogger - the MethodLogger to use, null to disable method logging

getMethodLogger

MethodLogger getMethodLogger()

Returns:

the MethodLogger being used, possibly null

databaseConnection

static DatabaseConnection databaseConnection(Database database,
                                             User user)
                                      throws DatabaseException

Constructs a new DatabaseConnection instance, based on the given Database and User

Parameters:

database - the database

user - the user for the db-connection

Returns:

a new DatabaseConnection instance

Throws:

DatabaseException - in case there is a problem connecting to the database

databaseConnection

static DatabaseConnection databaseConnection(Database database,
                                             Connection connection)
                                      throws DatabaseException

Constructs a new DatabaseConnection instance, based on the given Connection object. NB. auto commit is disabled on the Connection that is provided.

Parameters:

database - the database

connection - the Connection object to base this DatabaseConnection on

Returns:

a new DatabaseConnection instance

Throws:

DatabaseException - in case there is a problem with the connection