Package rife.database

Class DbQueryManager

java.lang.Object

rife.database.DbQueryManager

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

AbstractGenericQueryManager, DatabaseResources

public class DbQueryManager
extends Object
implements Cloneable

This is a convenience class to make it easy to control the queries that handle the retrieval, storage, update and removal of data in a database. All queries will be executed in a connection of the Datasource that's provided to the constructor of the DbQueryManager.

A collection of convenience methods have been provided to quickly execute queries in a variety of manners without having to worry about the logic behind it or having to remember to close the queries at the appropriate moment. These methods optionally interact with the DbPreparedStatementHandler and DbResultSetHandler classes to make it possible to fully customize the executed queries. The following categories of worry-free methods exist:

• execute an update query directly
• execute a customizable update query
• execute a customizable select query
• check the result rows of a customizable select query
• obtain the first value of a customizable select query
• fetch the first row of a customizable select query
• fetch the first bean of a customizable select query
• fetch all rows of a customizable select query
• fetch all beans of a customizable select query

Lower-level methods are also available for the sake of repetitive code-reduction. To obtain execute regular statements directly, use the executeQuery method.

Finally, since DbStatement and DbPreparedStatement instances preserve a reference to their result set, it's easy to iterate over the rows of a result set with the fetch or fetchAll methods.

Since:

1.0

See Also:

• DbPreparedStatement
• DbStatement
• DbRowProcessor
• DbPreparedStatementHandler
• DbResultSetHandler
• DbConnectionUser

Constructor Summary

Constructors

Constructor	Description
DbQueryManager(Datasource datasource)	Instantiates a new DbQueryManager object and ties it to the provided datasource.

Method Summary

Modifier and Type	Method	Description
Object	clone()	Simply clones the instance with the default clone method.
boolean	executeFetchAll(ReadQuery query, DbRowProcessor rowProcessor)	Safely and quickly fetches all the rows from the results of a select query.
boolean	executeFetchAll(ReadQuery query, DbRowProcessor rowProcessor, PreparedStatementHandler handler)	Safely fetches all the rows from the results of a customizable select query.
boolean	executeFetchAll(ReadQuery query, RowProcessor rowProcessor)	Convenience alternative to executeFetchAll(ReadQuery, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.
boolean	executeFetchAll(ReadQuery query, RowProcessor rowProcessor, PreparedStatementHandler handler)	Convenience alternative to executeFetchAll(ReadQuery, DbRowProcessor, PreparedStatementHandler) that uses a simplified RowProcessor that can be implemented with a lambda.
<BeanType> List<BeanType>	executeFetchAllBeans(ReadQuery query, Class<BeanType> beanClass)	Safely and quickly fetches the all the bean instances from the results of a select query.
<BeanType> List<BeanType>	executeFetchAllBeans(ReadQuery query, Class<BeanType> beanClass, PreparedStatementHandler handler)	Safely fetches the all the bean instances from the results of a customizable select query.
boolean	executeFetchFirst(ReadQuery query, DbRowProcessor rowProcessor)	Safely and quickly fetches the first row from the results of a select query.
boolean	executeFetchFirst(ReadQuery query, DbRowProcessor rowProcessor, PreparedStatementHandler handler)	Safely fetches the first row from the results of a customizable select query.
boolean	executeFetchFirst(ReadQuery query, RowProcessor rowProcessor)	Convenience alternative to executeFetchFirst(ReadQuery, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.
boolean	executeFetchFirst(ReadQuery query, RowProcessor rowProcessor, PreparedStatementHandler handler)	Convenience alternative to executeFetchFirst(ReadQuery, DbRowProcessor, PreparedStatementHandler) that uses a simplified RowProcessor that can be implemented with a lambda.
<BeanType> BeanType	executeFetchFirstBean(ReadQuery query, Class<BeanType> beanClass)	Safely and quickly fetches the first bean instance from the results of a select query.
<BeanType> BeanType	executeFetchFirstBean(ReadQuery query, Class<BeanType> beanClass, PreparedStatementHandler handler)	Safely fetches the first bean instance from the results of a customizable select query.
boolean	executeGetFirstBoolean(ReadQuery query)	Safely and quickly retrieves the first cell as a boolean from the results of a select query.
boolean	executeGetFirstBoolean(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a boolean from the results of a customizable select query.
byte	executeGetFirstByte(ReadQuery query)	Safely and quickly retrieves the first cell as a byte from the results of a select query.
byte	executeGetFirstByte(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a byte from the results of a customizable select query.
byte[]	executeGetFirstBytes(ReadQuery query)	Safely and quickly retrieves the first cell as a byte array from the results of a select query.
byte[]	executeGetFirstBytes(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a byte array from the results of a customizable select query.
Date	executeGetFirstDate(ReadQuery query)	Safely and quickly retrieves the first cell as a sql Date from the results of a select query.
Date	executeGetFirstDate(ReadQuery query, Calendar cal)	Safely and quickly retrieves the first cell as a sql Date from the results of a select query.
Date	executeGetFirstDate(ReadQuery query, Calendar cal, PreparedStatementHandler handler)	Safely retrieves the first cell as a sql Date from the results of a customizable select query.
Date	executeGetFirstDate(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a sql Date from the results of a customizable select query.
double	executeGetFirstDouble(ReadQuery query)	Safely and quickly retrieves the first cell as a double from the results of a select query.
double	executeGetFirstDouble(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a double from the results of a customizable select query.
float	executeGetFirstFloat(ReadQuery query)	Safely and quickly retrieves the first cell as a float from the results of a select query.
float	executeGetFirstFloat(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a float from the results of a customizable select query.
int	executeGetFirstInt(ReadQuery query)	Safely and quickly retrieves the first cell as a int from the results of a select query.
int	executeGetFirstInt(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a int from the results of a customizable select query.
long	executeGetFirstLong(ReadQuery query)	Safely and quickly retrieves the first cell as a long from the results of a select query.
long	executeGetFirstLong(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a long from the results of a customizable select query.
short	executeGetFirstShort(ReadQuery query)	Safely and quickly retrieves the first cell as a short from the results of a select query.
short	executeGetFirstShort(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a short from the results of a customizable select query.
String	executeGetFirstString(ReadQuery query)	Safely and quickly retrieves the first cell as a String from the results of a select query.
String	executeGetFirstString(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a String from the results of a customizable select query.
Time	executeGetFirstTime(ReadQuery query)	Safely and quickly retrieves the first cell as a sql Time from the results of a select query.
Time	executeGetFirstTime(ReadQuery query, Calendar cal)	Safely and quickly retrieves the first cell as a sql Time from the results of a select query.
Time	executeGetFirstTime(ReadQuery query, Calendar cal, PreparedStatementHandler handler)	Safely retrieves the first cell as a sql Time from the results of a customizable select query.
Time	executeGetFirstTime(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a sql Time from the results of a customizable select query.
Timestamp	executeGetFirstTimestamp(ReadQuery query)	Safely and quickly retrieves the first cell as a sql Timestamp from the results of a select query.
Timestamp	executeGetFirstTimestamp(ReadQuery query, Calendar cal)	Safely and quickly retrieves the first cell as a sql Timestamp from the results of a select query.
Timestamp	executeGetFirstTimestamp(ReadQuery query, Calendar cal, PreparedStatementHandler handler)	Safely retrieves the first cell as a sql Timestamp from the results of a customizable select query.
Timestamp	executeGetFirstTimestamp(ReadQuery query, PreparedStatementHandler handler)	Safely retrieves the first cell as a sql Timestamp from the results of a customizable select query.
boolean	executeHasResultRows(ReadQuery query)	Safely and quickly verifies if a select query returns any rows.
boolean	executeHasResultRows(ReadQuery query, PreparedStatementHandler handler)	Safely verifies if a customizable select query returns any rows.
DbStatement	executeQuery(ReadQuery query)	Executes a query statement in a connection of this DbQueryManager's Datasource.
<ResultType> ResultType	executeQuery(ReadQuery query, PreparedStatementHandler handler)	Executes a customizable select statement.
<ResultType> ResultType	executeResultQuery(ReadQuery query, DbResultSetHandler handler)	Executes a select statement and handle the results in a custom fashion.
int	executeUpdate(String sql)	Safely and quickly executes an update statement.
int	executeUpdate(Query query)	Safely and quickly executes an update statement.
int	executeUpdate(Query query, PreparedStatementHandler handler)	Safely execute an update statement.
<ResultType> ResultType	executeUseFirstAsciiStream(ReadQuery query, InputStreamUser user)	Safely and quickly retrieves the first cell as an ASCII InputStream from the results of a select query.
<ResultType> ResultType	executeUseFirstAsciiStream(ReadQuery query, InputStreamUser user, PreparedStatementHandler handler)	Safely retrieves the first cell as an ASCII InputStream from the results of a customizable select query.
<ResultType> ResultType	executeUseFirstBinaryStream(ReadQuery query, InputStreamUser user)	Safely and quickly retrieves the first cell as a binary InputStream from the results of a select query.
<ResultType> ResultType	executeUseFirstBinaryStream(ReadQuery query, InputStreamUser user, PreparedStatementHandler handler)	Safely retrieves the first cell as an binary InputStream from the results of a customizable select query.
<ResultType> ResultType	executeUseFirstCharacterStream(ReadQuery query, ReaderUser user)	Safely and quickly retrieves the first cell as a character Reader from the results of a select query.
<ResultType> ResultType	executeUseFirstCharacterStream(ReadQuery query, ReaderUser user, PreparedStatementHandler handler)	Safely retrieves the first cell as an character Reader from the results of a customizable select query.
boolean	fetch(ResultSet resultSet)	Fetches the next row of a result set without processing it in any way.
boolean	fetch(ResultSet resultSet, DbRowProcessor rowProcessor)	Fetches the next row of a result set and processes it through a DbRowProcessor.
boolean	fetch(ResultSet resultSet, RowProcessor rowProcessor)	Convenience alternative to fetch(ResultSet, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.
boolean	fetchAll(ResultSet resultSet, DbRowProcessor rowProcessor)	Fetches all the next rows of a result set and processes it through a DbRowProcessor.
boolean	fetchAll(ResultSet resultSet, RowProcessor rowProcessor)	Convenience alternative to fetchAll(ResultSet, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.
DbConnection	getConnection()	Obtains a DbConnection of this DbQueryManager's Datasource.
Datasource	getDatasource()	Retrieves the Datasource of this DbQueryManager.
<ResultType> ResultType	inTransaction(TransactionUser user)	Ensures that all the instructions that are executed in the provided DbTransactionUser instance are executed inside a transaction and committed afterwards.
void	inTransaction(TransactionUserWithoutResult user)	Convenience method that ensures that all the instructions that are executed in the provided TransactionUserWithoutResult instance, are executed inside a transaction and committed afterwards.
<ResultType> ResultType	reserveConnection(DbConnectionUser user)	Reserves a database connection for a particular thread for all the instructions that are executed in the provided DbConnectionUser instance.

Methods inherited from class java.lang.Object

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

Constructor Details

DbQueryManager

public DbQueryManager(Datasource datasource)

Instantiates a new DbQueryManager object and ties it to the provided datasource.

Parameters:

datasource - the datasource that will be used to obtain database connections from

Since:

1.0

Method Details

executeUpdate

public int executeUpdate(String sql)
                  throws DatabaseException

Safely and quickly executes an update statement. It relies on the wrapped DbStatement.executeUpdate(String) method, but also automatically closes the statement after its execution.

This method is typically used in situations where one static update query needs to be executed without any parametrization or other processing.

Example

var manager = new DbQueryManager(datasource);
 var count = manager.executeUpdate("INSERT INTO person (name) VALUES ('me')");

Parameters:

sql - the sql query that has to be executed

Returns:

the row count for the executed query

Throws:

DatabaseException - see DbStatement.executeUpdate(String)

Since:

1.0

See Also:

• DbStatement.executeUpdate(String)
• executeUpdate(Query)

executeUpdate

public int executeUpdate(Query query)
                  throws DatabaseException

Safely and quickly executes an update statement. It relies on the wrapped DbStatement.executeUpdate(Query) method, but also automatically closes the statement after its execution.

This method is typically used in situations where one static update query needs to be executed without any parametrization or other processing.

Example

var manager = new DbQueryManager(datasource);
 var insert = new Insert(datasource)
     .into("person").field("name", "me");
 var count = manager.executeUpdate(insert);

Parameters:

query - the query builder instance that needs to be executed

Returns:

the row count for the executed query

Throws:

DatabaseException - see DbStatement.executeUpdate(Query)

Since:

1.0

See Also:

• DbStatement.executeUpdate(Query)
• executeUpdate(String)

executeUpdate

public int executeUpdate(Query query,
 PreparedStatementHandler handler)
                  throws DatabaseException

Safely execute an update statement. It relies on the wrapped DbPreparedStatement.executeUpdate() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

This method is typically used when you need to fully customize a query at runtime, but still want to benefit of a safety net that ensures that the allocated statement will be closed.

Example

var manager = new DbQueryManager(datasource);
 var insert = new Insert(datasource)
     .into("person").fieldParameter("name");
 final var name = "me";
 var count = manager.executeUpdate(insert,
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the row count for the executed query

Throws:

DatabaseException - see DbPreparedStatement.executeUpdate()

Since:

1.0

See Also:

• DbPreparedStatement.executeUpdate()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeHasResultRows

public boolean executeHasResultRows(ReadQuery query)
                             throws DatabaseException

Safely and quickly verifies if a select query returns any rows. It relies on the wrapped DbResultSet.hasResultRows() method, but also automatically closes the statement after its execution.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person");
 var result = manager.executeHasResultRows(select);
 

Parameters:

query - the query builder instance that needs to be executed

Returns:

true when rows were returned by the query; or

false otherwise

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.hasResultRows()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.hasResultRows()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeHasResultRows

public boolean executeHasResultRows(ReadQuery query,
 PreparedStatementHandler handler)
                             throws DatabaseException

Safely verifies if a customizable select query returns any rows. It relies on the wrapped DbResultSet.hasResultRows() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").whereParameter("name", "=");
 var String name = "you";
 var result = manager.executeHasResultRows(select,
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution

Returns:

true when rows were returned by the query; or

false otherwise

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.hasResultRows()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.hasResultRows()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstString

public String executeGetFirstString(ReadQuery query)
                             throws DatabaseException

Safely and quickly retrieves the first cell as a String from the results of a select query. It relies on the wrapped DbResultSet.getFirstString() method, but also automatically closes the statement after its execution.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
      .field("name").from("person");
 var result = manager.executeGetFirstString(select);
 

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first String in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstString()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstString()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstString

public String executeGetFirstString(ReadQuery query,
 PreparedStatementHandler handler)
                             throws DatabaseException

Safely retrieves the first cell as a String from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstString() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .field("first").from("person").whereParameter("last", "=");
 final var last = "Smith";
 var result = manager.executeGetFirstString(select,
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first String in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstString()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstString()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstBoolean

public boolean executeGetFirstBoolean(ReadQuery query)
                               throws DatabaseException

Safely and quickly retrieves the first cell as a boolean from the results of a select query. It relies on the wrapped DbResultSet.getFirstBoolean() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first boolean in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstBoolean()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstBoolean()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstBoolean

public boolean executeGetFirstBoolean(ReadQuery query,
 PreparedStatementHandler handler)
                               throws DatabaseException

Safely retrieves the first cell as a boolean from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstBoolean() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first boolean in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstBoolean()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstBoolean()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstByte

public byte executeGetFirstByte(ReadQuery query)
                         throws DatabaseException

Safely and quickly retrieves the first cell as a byte from the results of a select query. It relies on the wrapped DbResultSet.getFirstByte() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first byte in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstByte()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstByte()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstByte

public byte executeGetFirstByte(ReadQuery query,
 PreparedStatementHandler handler)
                         throws DatabaseException

Safely retrieves the first cell as a byte from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstByte() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first byte in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstByte()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstByte()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstShort

public short executeGetFirstShort(ReadQuery query)
                           throws DatabaseException

Safely and quickly retrieves the first cell as a short from the results of a select query. It relies on the wrapped DbResultSet.getFirstShort() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first short in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstShort()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstShort()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstShort

public short executeGetFirstShort(ReadQuery query,
 PreparedStatementHandler handler)
                           throws DatabaseException

Safely retrieves the first cell as a short from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstShort() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first short in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstShort()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstShort()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstInt

public int executeGetFirstInt(ReadQuery query)
                       throws DatabaseException

Safely and quickly retrieves the first cell as a int from the results of a select query. It relies on the wrapped DbResultSet.getFirstInt() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first int in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstInt()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstInt()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstInt

public int executeGetFirstInt(ReadQuery query,
 PreparedStatementHandler handler)
                       throws DatabaseException

Safely retrieves the first cell as a int from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstInt() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first int in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstInt()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstInt()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstLong

public long executeGetFirstLong(ReadQuery query)
                         throws DatabaseException

Safely and quickly retrieves the first cell as a long from the results of a select query. It relies on the wrapped DbResultSet.getFirstLong() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first long in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstLong()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstLong()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstLong

public long executeGetFirstLong(ReadQuery query,
 PreparedStatementHandler handler)
                         throws DatabaseException

Safely retrieves the first cell as a long from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstLong() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first long in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstLong()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstLong()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstFloat

public float executeGetFirstFloat(ReadQuery query)
                           throws DatabaseException

Safely and quickly retrieves the first cell as a float from the results of a select query. It relies on the wrapped DbResultSet.getFirstFloat() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first float in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstFloat()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstFloat()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstFloat

public float executeGetFirstFloat(ReadQuery query,
 PreparedStatementHandler handler)
                           throws DatabaseException

Safely retrieves the first cell as a float from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstFloat() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first float in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstFloat()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstFloat()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstDouble

public double executeGetFirstDouble(ReadQuery query)
                             throws DatabaseException

Safely and quickly retrieves the first cell as a double from the results of a select query. It relies on the wrapped DbResultSet.getFirstDouble() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first double in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstDouble()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstDouble()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstDouble

public double executeGetFirstDouble(ReadQuery query,
 PreparedStatementHandler handler)
                             throws DatabaseException

Safely retrieves the first cell as a double from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstDouble() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first double in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstDouble()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstDouble()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstBytes

public byte[] executeGetFirstBytes(ReadQuery query)
                            throws DatabaseException

Safely and quickly retrieves the first cell as a byte array from the results of a select query. It relies on the wrapped DbResultSet.getFirstBytes() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first byte array in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstBytes()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstBytes()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstBytes

public byte[] executeGetFirstBytes(ReadQuery query,
 PreparedStatementHandler handler)
                            throws DatabaseException

Safely retrieves the first cell as a byte array from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstBytes() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first byte array in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstBytes()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstBytes()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstDate

public Date executeGetFirstDate(ReadQuery query)
                         throws DatabaseException

Safely and quickly retrieves the first cell as a sql Date from the results of a select query. It relies on the wrapped DbResultSet.getFirstDate() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first sql Date in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstDate()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstDate()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstDate

public Date executeGetFirstDate(ReadQuery query,
 PreparedStatementHandler handler)
                         throws DatabaseException

Safely retrieves the first cell as a sql Date from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstDate() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first sql Date in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstDate()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstDate()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstDate

public Date executeGetFirstDate(ReadQuery query,
 Calendar cal)
                         throws DatabaseException

Safely and quickly retrieves the first cell as a sql Date from the results of a select query. It relies on the wrapped DbResultSet.getFirstDate(Calendar) method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

cal - the Calendar object to use in constructing the date

Returns:

the first sql Date in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstDate(Calendar)

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstDate(Calendar)
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstDate

public Date executeGetFirstDate(ReadQuery query,
 Calendar cal,
 PreparedStatementHandler handler)
                         throws DatabaseException

Safely retrieves the first cell as a sql Date from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstDate(Calendar) method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

cal - the Calendar object to use in constructing the date

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first sql Date in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstDate(Calendar)

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstDate(Calendar)
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTime

public Time executeGetFirstTime(ReadQuery query)
                         throws DatabaseException

Safely and quickly retrieves the first cell as a sql Time from the results of a select query. It relies on the wrapped DbResultSet.getFirstTime() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first sql Time in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTime()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTime()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTime

public Time executeGetFirstTime(ReadQuery query,
 PreparedStatementHandler handler)
                         throws DatabaseException

Safely retrieves the first cell as a sql Time from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstTime() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first sql Time in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTime()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTime()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTime

public Time executeGetFirstTime(ReadQuery query,
 Calendar cal)
                         throws DatabaseException

Safely and quickly retrieves the first cell as a sql Time from the results of a select query. It relies on the wrapped DbResultSet.getFirstTime(Calendar) method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

cal - the Calendar object to use in constructing the time

Returns:

the first sql Time in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTime(Calendar)

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTime(Calendar)
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTime

public Time executeGetFirstTime(ReadQuery query,
 Calendar cal,
 PreparedStatementHandler handler)
                         throws DatabaseException

Safely retrieves the first cell as a sql Time from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstTime(Calendar) method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

cal - the Calendar object to use in constructing the time

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first sql Time in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTime(Calendar)

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTime(Calendar)
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTimestamp

public Timestamp executeGetFirstTimestamp(ReadQuery query)
                                   throws DatabaseException

Safely and quickly retrieves the first cell as a sql Timestamp from the results of a select query. It relies on the wrapped DbResultSet.getFirstTimestamp() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

Returns:

the first sql Timestamp in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTimestamp()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTimestamp()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTimestamp

public Timestamp executeGetFirstTimestamp(ReadQuery query,
 PreparedStatementHandler handler)
                                   throws DatabaseException

Safely retrieves the first cell as a sql Timestamp from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstTimestamp() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first sql Timestamp in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTimestamp()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTimestamp()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTimestamp

public Timestamp executeGetFirstTimestamp(ReadQuery query,
 Calendar cal)
                                   throws DatabaseException

Safely and quickly retrieves the first cell as a sql Timestamp from the results of a select query. It relies on the wrapped DbResultSet.getFirstTimestamp(Calendar) method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

cal - the Calendar object to use in constructing the timestamp

Returns:

the first sql Timestamp in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTimestamp(Calendar)

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTimestamp(Calendar)
• PreparedStatementHandler
• DbPreparedStatementHandler

executeGetFirstTimestamp

public Timestamp executeGetFirstTimestamp(ReadQuery query,
 Calendar cal,
 PreparedStatementHandler handler)
                                   throws DatabaseException

Safely retrieves the first cell as a sql Timestamp from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstTimestamp(Calendar) method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

cal - the Calendar object to use in constructing the timestamp

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the first sql Timestamp in the query's result set

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstTimestamp(Calendar)

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstTimestamp(Calendar)
• PreparedStatementHandler
• DbPreparedStatementHandler

executeUseFirstAsciiStream

public <ResultType> ResultType executeUseFirstAsciiStream(ReadQuery query,
 InputStreamUser user)
                                                   throws DatabaseException,
InnerClassException

Safely and quickly retrieves the first cell as an ASCII InputStream from the results of a select query. It relies on the wrapped DbResultSet.getFirstAsciiStream() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

user - an instance of InputStreamUser that contains the logic that will be executed with this stream

Returns:

the return value from the useInputStream method of the provided InputStreamUser instance

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstAsciiStream()

InnerClassException - when errors occurs inside the InputStreamUser

Since:

1.0

See Also:

• InputStreamUser
• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstAsciiStream()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeUseFirstAsciiStream

public <ResultType> ResultType executeUseFirstAsciiStream(ReadQuery query,
 InputStreamUser user,
 PreparedStatementHandler handler)
                                                   throws DatabaseException,
InnerClassException

Safely retrieves the first cell as an ASCII InputStream from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstAsciiStream() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

user - an instance of InputStreamUser that contains the logic that will be executed with this stream

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the return value from the useInputStream method of the provided InputStreamUser instance

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstAsciiStream()

InnerClassException - when errors occurs inside the InputStreamUser

Since:

1.0

See Also:

• InputStreamUser
• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstAsciiStream()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeUseFirstCharacterStream

public <ResultType> ResultType executeUseFirstCharacterStream(ReadQuery query,
 ReaderUser user)
                                                       throws DatabaseException,
InnerClassException

Safely and quickly retrieves the first cell as a character Reader from the results of a select query. It relies on the wrapped DbResultSet.getFirstCharacterStream() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

user - an instance of ReaderUser that contains the logic that will be executed with this reader

Returns:

the return value from the useReader method of the provided ReaderUser instance

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstCharacterStream()

InnerClassException - when errors occurs inside the ReaderUser

Since:

1.0

See Also:

• ReaderUser
• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstCharacterStream()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeUseFirstCharacterStream

public <ResultType> ResultType executeUseFirstCharacterStream(ReadQuery query,
 ReaderUser user,
 PreparedStatementHandler handler)
                                                       throws DatabaseException,
InnerClassException

Safely retrieves the first cell as an character Reader from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstCharacterStream() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

user - an instance of ReaderUser that contains the logic that will be executed with this reader

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the return value from the useReader method of the provided ReaderUser instance

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstCharacterStream()

InnerClassException - when errors occurs inside the ReaderUser

Since:

1.0

See Also:

• ReaderUser
• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstCharacterStream()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeUseFirstBinaryStream

public <ResultType> ResultType executeUseFirstBinaryStream(ReadQuery query,
 InputStreamUser user)
                                                    throws DatabaseException,
InnerClassException

Safely and quickly retrieves the first cell as a binary InputStream from the results of a select query. It relies on the wrapped DbResultSet.getFirstBinaryStream() method, but also automatically closes the statement after its execution.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

user - an instance of InputStreamUser that contains the logic that will be executed with this stream

Returns:

the return value from the useInputStream method of the provided InputStreamUser instance

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstBinaryStream()

InnerClassException - when errors occurs inside the InputStreamUser

Since:

1.0

See Also:

• InputStreamUser
• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstBinaryStream()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeUseFirstBinaryStream

public <ResultType> ResultType executeUseFirstBinaryStream(ReadQuery query,
 InputStreamUser user,
 PreparedStatementHandler handler)
                                                    throws DatabaseException,
InnerClassException

Safely retrieves the first cell as an binary InputStream from the results of a customizable select query. It relies on the wrapped DbResultSet.getFirstBinaryStream() method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Refer to executeGetFirstString for an example code snippet, it's 100% analogous.

Parameters:

query - the query builder instance that needs to be executed

user - an instance of InputStreamUser that contains the logic that will be executed with this stream

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the return value from the useInputStream method of the provided InputStreamUser instance

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and DbResultSet.getFirstBinaryStream()

InnerClassException - when errors occurs inside the InputStreamUser

Since:

1.0

See Also:

• InputStreamUser
• DbPreparedStatement.executeQuery()
• DbResultSet.getFirstBinaryStream()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeFetchFirst

public boolean executeFetchFirst(ReadQuery query,
 DbRowProcessor rowProcessor)
                          throws DatabaseException

Safely and quickly fetches the first row from the results of a select query. It relies on the wrapped fetch(ResultSet, DbRowProcessor) method, but automatically closes the statement after its execution.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
  .from("person").where("name", "=", "me");
 var processor = new YourProcessor();
 var result = manager.executeFetchFirst(select,
     resultSet -> resultSet.getString("name"));

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a DbRowProcessor instance, if it's null no processing will be performed on the fetched row

Returns:

true if a row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetch(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• fetch(ResultSet, DbRowProcessor)
• DbRowProcessor

executeFetchFirst

public boolean executeFetchFirst(ReadQuery query,
 RowProcessor rowProcessor)
                          throws DatabaseException

Convenience alternative to executeFetchFirst(ReadQuery, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a RowProcessor instance, if it's null no processing will be performed on the fetched row

Returns:

true if a row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetchAll(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchFirst(ReadQuery, DbRowProcessor)
• RowProcessor

executeFetchFirst

public boolean executeFetchFirst(ReadQuery query,
 DbRowProcessor rowProcessor,
 PreparedStatementHandler handler)
                          throws DatabaseException

Safely fetches the first row from the results of a customizable select query. It relies on the wrapped fetch(ResultSet, DbRowProcessor) method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
      .from("person").whereParameter("name", "=");
 var processor = new YourProcessor();
 final var name = "you";
 var result = manager.executeFetchFirst(select,
     resultSet -> resultSet.getString("name"),
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a DbRowProcessor instance, if it's null no processing will be performed on the fetched row

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

true if a row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetch(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• fetch(ResultSet, DbRowProcessor)
• DbRowProcessor

executeFetchFirst

public boolean executeFetchFirst(ReadQuery query,
 RowProcessor rowProcessor,
 PreparedStatementHandler handler)

Convenience alternative to executeFetchFirst(ReadQuery, DbRowProcessor, PreparedStatementHandler) that uses a simplified RowProcessor that can be implemented with a lambda.

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a RowProcessor instance, if it's null no processing will be performed on the fetched row

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

true if a row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetchAll(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchFirst(ReadQuery, DbRowProcessor, PreparedStatementHandler)
• RowProcessor

executeFetchFirstBean

public <BeanType> BeanType executeFetchFirstBean(ReadQuery query,
 Class<BeanType> beanClass)
                                          throws DatabaseException

Safely and quickly fetches the first bean instance from the results of a select query. It relies on the wrapped executeFetchFirst(ReadQuery, DbRowProcessor) method, but automatically uses an appropriate DbBeanFetcher instance and returns the resulting bean.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").fields(Person.class);
 var person = manager.executeFetchFirstBean(select, Person.class);

Parameters:

query - the query builder instance that needs to be executed

beanClass - the class of the bean

Returns:

and instance of the bean if it was retrieved successfully; or null if it couldn't be found

Throws:

DatabaseException - see DbBeanFetcher and executeFetchFirst(ReadQuery, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchFirst(ReadQuery, DbRowProcessor)
• DbBeanFetcher

executeFetchFirstBean

public <BeanType> BeanType executeFetchFirstBean(ReadQuery query,
 Class<BeanType> beanClass,
 PreparedStatementHandler handler)
                                          throws DatabaseException

Safely fetches the first bean instance from the results of a customizable select query. It relies on the wrapped executeFetchFirst(ReadQuery, DbRowProcessor) method, but automatically uses an appropriate DbBeanFetcher instance, returns the resulting bean and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").fields(Person.class).whereParameter("name", "=");
 final var name = "you";
 var person = manager.executeFetchFirstBean(select, Person.class,
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

beanClass - the class of the bean

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

and instance of the bean if it was retrieved successfully; or null if it couldn't be found

Throws:

DatabaseException - see DbBeanFetcher and executeFetchFirst(ReadQuery, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchFirst(ReadQuery, DbRowProcessor)
• DbBeanFetcher

executeFetchAll

public boolean executeFetchAll(ReadQuery query,
 DbRowProcessor rowProcessor)
                        throws DatabaseException

Safely and quickly fetches all the rows from the results of a select query. It relies on the wrapped fetchAll(ResultSet, DbRowProcessor) method, but automatically closes the statement after its execution.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").where("gender", "=", "m");
 var result = manager.executeFetchAll(select,
     resultSet -> resultSet.getString("name"));

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a DbRowProcessor instance, if it's null no processing will be performed on the fetched rows

Returns:

true if rows were retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetchAll(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• fetchAll(ResultSet, DbRowProcessor)
• DbRowProcessor

executeFetchAll

public boolean executeFetchAll(ReadQuery query,
 RowProcessor rowProcessor)
                        throws DatabaseException

Convenience alternative to executeFetchAll(ReadQuery, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a RowProcessor instance, if it's null no processing will be performed on the fetched rows

Returns:

true if a row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetchAll(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchAll(ReadQuery, DbRowProcessor)
• RowProcessor

executeFetchAll

public boolean executeFetchAll(ReadQuery query,
 DbRowProcessor rowProcessor,
 PreparedStatementHandler handler)
                        throws DatabaseException

Safely fetches all the rows from the results of a customizable select query. It relies on the wrapped fetchAll(ResultSet, DbRowProcessor) method, but also automatically closes the statement after its execution and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").whereParameter("gender", "=");
 final String name = "m";
 var result = manager.executeFetchAll(select,
     resultSet -> resultSet.getString("name"),
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a DbRowProcessor instance, if it's null no processing will be performed on the fetched row

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

true if rows were retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetchAll(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• fetchAll(ResultSet, DbRowProcessor)
• DbRowProcessor

executeFetchAll

public boolean executeFetchAll(ReadQuery query,
 RowProcessor rowProcessor,
 PreparedStatementHandler handler)
                        throws DatabaseException

Convenience alternative to executeFetchAll(ReadQuery, DbRowProcessor, PreparedStatementHandler) that uses a simplified RowProcessor that can be implemented with a lambda.

Parameters:

query - the query builder instance that needs to be executed

rowProcessor - a RowProcessor instance, if it's null no processing will be performed on the fetched rows

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

true if a row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - see DbPreparedStatement.executeQuery() and fetchAll(ResultSet, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchAll(ReadQuery, DbRowProcessor, PreparedStatementHandler)
• RowProcessor

executeFetchAllBeans

public <BeanType> List<BeanType> executeFetchAllBeans(ReadQuery query,
 Class<BeanType> beanClass)
                                               throws DatabaseException

Safely and quickly fetches the all the bean instances from the results of a select query. It relies on the wrapped executeFetchAll(ReadQuery, DbRowProcessor) method, but automatically uses an appropriate DbBeanFetcher instance and returns the results.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").fields(Person.class).where("gender", "=", "m");
 var people = manager.executeFetchAllBeans(select, Person.class);

Parameters:

query - the query builder instance that needs to be executed

beanClass - the class of the bean

Returns:

a List instance with all the beans, the list is empty if no beans could be returned

Throws:

DatabaseException - see DbBeanFetcher and executeFetchAll(ReadQuery, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchAll(ReadQuery, DbRowProcessor)
• DbBeanFetcher

executeFetchAllBeans

public <BeanType> List<BeanType> executeFetchAllBeans(ReadQuery query,
 Class<BeanType> beanClass,
 PreparedStatementHandler handler)
                                               throws DatabaseException

Safely fetches the all the bean instances from the results of a customizable select query. It relies on the wrapped executeFetchAll(ReadQuery, DbRowProcessor) method, but automatically uses an appropriate DbBeanFetcher instance, returns the results and allows customization of the prepared statement through an optional instance of PreparedStatementHandler.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource)
     .from("person").fields(Person.class).whereParameter("gender", "=");
 final String name = "m";
 var people = manager.executeFetchAllBeans(select, Person.class,
     statement -> statement.setString("name", name));
 

Parameters:

query - the query builder instance that needs to be executed

beanClass - the class of the bean

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

a List instance with all the beans, the list is empty if no beans could be returned

Throws:

DatabaseException - see DbBeanFetcher and executeFetchAll(ReadQuery, DbRowProcessor)

Since:

1.0

See Also:

• executeFetchAll(ReadQuery, DbRowProcessor)
• DbBeanFetcher

executeQuery

public <ResultType> ResultType executeQuery(ReadQuery query,
 PreparedStatementHandler handler)
                                     throws DatabaseException

Executes a customizable select statement. It relies on the wrapped DbPreparedStatement.executeQuery() method, but also automatically closes the statement after its execution and allows complete customization of the prepared statement through an optional instance of PreparedStatementHandler.

This method is typically used when you need to fully customize a query at runtime, but still want to benefit of a safety net that ensures that the allocated statement will be closed. Often another more specialized method in this class will already serve your needs, so be sure to verify that you actually need to intervene on every front.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource);
 select
    .field("first")
    .field("last")
    .from("person")
    .whereParameter("name", "=");
 final var name = "you";
 String result = (String)manager.executeQuery(select, new DbPreparedStatementHandler() {
        public void setParameters(DbPreparedStatement statement)
        {
            statement
                .setString("name", name);
        }

        public Object concludeResults(DbResultSet result set)
        throws SQLException
        {
            return result set.getString("first")+" "+result set.getString("last");
        }
    });

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of PreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all

Returns:

the object that was returned by the overridden concludeResults method; or

null if this method wasn't overridden

Throws:

DatabaseException - see DbPreparedStatement.executeQuery()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• PreparedStatementHandler
• DbPreparedStatementHandler

executeResultQuery

public <ResultType> ResultType executeResultQuery(ReadQuery query,
 DbResultSetHandler handler)
                                           throws DatabaseException

Executes a select statement and handle the results in a custom fashion. It relies on the wrapped DbPreparedStatement.executeQuery() method, but also automatically closes the statement after its execution and allows interaction with the result set through an optional instance of DbResultSetHandler.

This method is typically used when you need to interact with the results of a query, but still want to benefit of a safety net that ensures that the allocated statement will be closed. Often another more specialized method in this class will already serve your needs, so be sure to verify that there isn't another one that's better suited.

Example

var manager = new DbQueryManager(datasource);
 var select = new Select(datasource);
 select
    .field("first")
    .field("last")
    .from("person");
 String result = (String)manager.executeResultQuery(select, new DbResultSetHandler() {
        public Object concludeResults(DbResultSet result set)
        throws SQLException {
            return result set.getString("first")+" "+result set.getString("last");
        }
    });

Parameters:

query - the query builder instance that needs to be executed

handler - an instance of DbResultSetHandler that will be used to handle the results of the query execution; or null if you don't want to customize it at all

Returns:

the object that was returned by the overridden concludeResults method; or

null if this method wasn't overridden

Throws:

DatabaseException - see DbPreparedStatement.executeQuery()

Since:

1.0

See Also:

• DbPreparedStatement.executeQuery()
• DbResultSetHandler

reserveConnection

public <ResultType> ResultType reserveConnection(DbConnectionUser user)
                                          throws InnerClassException,
DatabaseException

Reserves a database connection for a particular thread for all the instructions that are executed in the provided DbConnectionUser instance.

This is typically used to ensure that a series of operations is done with the same connection, even though a database pool is used in the background.

Example

Person person;
 final var store_data = new Insert(datasource).into("person").fields(person);
 final var get_last_id = new Select(datasource).from("person").field("LAST_INSERT_ID()");
 final var manager = new DbQueryManager(datasource);
 int id = ((Integer)manager.reserveConnection(new DbConnectionUser() {
        public Integer useConnection(DbConnection connection) {
            manager.executeUpdate(store_data);
            return new Integer(manager.executeGetFirstInt(get_last_id));
        }
    })).intValue();

Parameters:

user - an instance of DbConnectionUser that contains the logic that will be executed

Returns:

the return value from the useConnection method of the provided DbConnectionUser instance

Throws:

DatabaseException - when errors occurs during the reservation of a connection for this thread

InnerClassException - when errors occurs inside the DbConnectionUser

Since:

1.0

See Also:

• DbConnectionUser.useConnection(DbConnection)

inTransaction

public <ResultType> ResultType inTransaction(TransactionUser user)
                                      throws InnerClassException,
DatabaseException

Ensures that all the instructions that are executed in the provided DbTransactionUser instance are executed inside a transaction and committed afterwards. This doesn't mean that a new transaction will always be created. If a transaction is already active, it will simply be re-used. The commit will also only be take place if a new transaction has actually been started, otherwise it's the responsibility of the enclosing code to execute the commit. If a runtime exception occurs during the execution and a new transaction has been started beforehand, it will be automatically rolled back.

If you need to explicitly roll back an active transaction, use the rollback method of the DbTransactionUser class. If you use a regular rollback method, it's possible that you're inside a nested transaction executed and that after the rollback, other logic continues to be executed outside the transaction. Using the correct rollback method, stops the execution of the active DbTransactionUser and breaks out of any number of them nesting.

It's recommended to always use transactions through this method since it ensures that transactional code can be re-used and enclosed in other transactional code. Correctly using the regular transaction-related methods requires great care and planning and often results in error-prone and not reusable code.

Example

final var insert = new Insert(mDatasource).into("valuelist").field("value", 232);
 final var manager = new DbQueryManager(datasource);
 manager.inTransaction(() -> {
        manager.executeUpdate(insert);
        manager.executeUpdate(insert);
    });
 

Parameters:

user - an instance of TransactionUser that contains the logic that will be executed

Returns:

the return value from the useTransaction method of the provided DbTransactionUser instance

Throws:

DatabaseException - when errors occurs during the handling of the transaction

InnerClassException - when errors occurs inside the DbTransactionUser

Since:

1.0

See Also:

• DbTransactionUser.useTransaction()
• DbTransactionUserWithoutResult.useTransactionWithoutResult()

inTransaction

public void inTransaction(TransactionUserWithoutResult user)
                   throws InnerClassException,
DatabaseException

Convenience method that ensures that all the instructions that are executed in the provided TransactionUserWithoutResult instance, are executed inside a transaction and committed afterwards.

Everything of inTransaction(TransactionUser) applies but instead of requiring a result to be returned, it's assumed that none will, making your code cleaner.

Parameters:

user - an instance of TransactionUserWithoutResult that contains the logic that will be executed

Throws:

DatabaseException - when errors occurs during the handling of the transaction

InnerClassException - when errors occurs inside the DbTransactionUser

Since:

1.0

See Also:

• TransactionUserWithoutResult.useTransaction()
• inTransaction(TransactionUser)

executeQuery

public DbStatement executeQuery(ReadQuery query)
                         throws DatabaseException

Executes a query statement in a connection of this DbQueryManager's Datasource. Functions exactly as the wrapped DbStatement.executeQuery(ReadQuery) method.

Note that the statement will not be automatically closed since using this method implies that you still have to work with the result set.

Parameters:

query - the query builder instance that should be executed

Returns:

the statement that has been executed

Throws:

DatabaseException - see DbStatement.executeQuery(ReadQuery)

Since:

1.0

See Also:

• DbStatement.executeQuery(ReadQuery)

fetch

public boolean fetch(ResultSet resultSet)
              throws DatabaseException

Fetches the next row of a result set without processing it in any way.

Parameters:

resultSet - a valid ResultSet instance

Returns:

true if a new row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - when an error occurred during the fetch of the next row in the result set

Since:

1.0

See Also:

• fetch(ResultSet, DbRowProcessor)

fetch

public boolean fetch(ResultSet resultSet,
 DbRowProcessor rowProcessor)
              throws DatabaseException

Fetches the next row of a result set and processes it through a DbRowProcessor.

Parameters:

resultSet - a valid ResultSet instance

rowProcessor - a DbRowProcessor instance, if it's null no processing will be performed on the fetched row

Returns:

true if a new row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - when an error occurred during the fetch of the next row in the result set

Since:

1.0

See Also:

• fetch(ResultSet)
• DbRowProcessor

fetch

public boolean fetch(ResultSet resultSet,
 RowProcessor rowProcessor)
              throws DatabaseException

Convenience alternative to fetch(ResultSet, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.

Parameters:

resultSet - a valid ResultSet instance

rowProcessor - a RowProcessor instance, if it's null no processing will be performed on the fetched row

Returns:

true if a new row was retrieved; or

false if there are no more rows .

Throws:

DatabaseException - when an error occurred during the fetch of the next row in the result set

Since:

1.0

See Also:

• fetch(ResultSet, DbRowProcessor)
• RowProcessor

fetchAll

public boolean fetchAll(ResultSet resultSet,
 DbRowProcessor rowProcessor)
                 throws DatabaseException

Fetches all the next rows of a result set and processes it through a DbRowProcessor.

Parameters:

resultSet - a valid ResultSet instance

rowProcessor - a DbRowProcessor instance, if it's null no processing will be performed on the fetched rows

Returns:

true if rows were fetched; or

false if the result set contained no rows.

Throws:

DatabaseException - when an error occurred during the fetch of the next rows in the result set

Since:

1.0

See Also:

• DbRowProcessor

fetchAll

public boolean fetchAll(ResultSet resultSet,
 RowProcessor rowProcessor)
                 throws DatabaseException

Convenience alternative to fetchAll(ResultSet, DbRowProcessor) that uses a simplified RowProcessor that can be implemented with a lambda.

Parameters:

resultSet - a valid ResultSet instance

rowProcessor - a RowProcessor instance, if it's null no processing will be performed on the fetched rows

Returns:

true if rows were fetched; or

false if the result set contained no rows.

Throws:

DatabaseException - when an error occurred during the fetch of the next rows in the result set

Since:

1.0

See Also:

• fetchAll(ResultSet, DbRowProcessor)
• RowProcessor

getConnection

public DbConnection getConnection()
                           throws DatabaseException

Obtains a DbConnection of this DbQueryManager's Datasource. Functions exactly as the wrapped Datasource.getConnection() method.

Returns:

the requested DbConnection

Throws:

DatabaseException - see Datasource.getConnection()

Since:

1.0

See Also:

• Datasource.getConnection()

getDatasource

public Datasource getDatasource()

Retrieves the Datasource of this DbQueryManager.

Returns:

the requested Datasource

Since:

1.0

clone

public Object clone()

Simply clones the instance with the default clone method. This creates a shallow copy of all fields and the clone will in fact just be another reference to the same underlying data. The independence of each cloned instance is consciously not respected since they rely on resources that can't be cloned.

Overrides:

clone in class Object

Returns:

a clone of this instance

Since:

1.0