com.uwyn.rife.database
Class DbQueryManager

java.lang.Object
  extended by com.uwyn.rife.database.DbQueryManager
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
AbstractGenericQueryManager, DatabaseContent, DatabaseContentStore, DatabaseMailQueue, DatabaseRawStore, DatabaseRemember, DatabaseResources, DatabaseScheduler, DatabaseSessions, DatabaseSessionValidator, DatabaseTaskoptions, DatabaseTasks, DatabaseUsers

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:

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 resultset, it's easy to iterate over the rows of a resultset with the fetch or fetchAll methods.

Since:
1.0
Version:
$Revision: 3784 $
Author:
Geert Bevin (gbevin[remove] at uwyn dot com)
See Also:
DbPreparedStatement, DbStatement, DbRowProcessor, DbPreparedStatementHandler, DbResultSetHandler, DbConnectionUser

Constructor Summary
DbQueryManager(Datasource datasource)
          Instantiates a new DbQueryManager object and ties it to the provided datasource.
 
Method Summary
 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, DbPreparedStatementHandler handler)
          Safely fetches all the rows from the results of a customizable select query.
<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, DbPreparedStatementHandler 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, DbPreparedStatementHandler handler)
          Safely fetches the first row from the results of a customizable select query.
<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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler handler)
          Safely retrieves the first cell as a sql Date from the results of a customizable select query.
 Date executeGetFirstDate(ReadQuery query, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler handler)
          Safely retrieves the first cell as a sql Time from the results of a customizable select query.
 Time executeGetFirstTime(ReadQuery query, DbPreparedStatementHandler 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, DbPreparedStatementHandler handler)
          Safely retrieves the first cell as a sql Timestamp from the results of a customizable select query.
 Timestamp executeGetFirstTimestamp(ReadQuery query, DbPreparedStatementHandler 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, DbPreparedStatementHandler 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, DbPreparedStatementHandler handler)
          Executes a customizable select statement.
<ResultType>
ResultType
executeQuery(ReadQuery query, DbResultSetHandler handler)
          Executes a select statement and handle the results in a custom fashion.
 int executeUpdate(Query query)
          Safely and quickly executes an update statement.
 int executeUpdate(Query query, DbPreparedStatementHandler handler)
          Safely execute an updates statement.
 int executeUpdate(String sql)
          Safely and quickly executes 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, DbPreparedStatementHandler 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 an binary InputStream from the results of a select query.
<ResultType>
ResultType
executeUseFirstBinaryStream(ReadQuery query, InputStreamUser user, DbPreparedStatementHandler 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 an character Reader from the results of a select query.
<ResultType>
ResultType
executeUseFirstCharacterStream(ReadQuery query, ReaderUser user, DbPreparedStatementHandler 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 resultset without processing it in any way.
 boolean fetch(ResultSet resultSet, DbRowProcessor rowProcessor)
          Fetches the next row of a resultset and processes it through a DbRowProcessor.
 boolean fetchAll(ResultSet resultSet, DbRowProcessor rowProcessor)
          Fetches all the next rows of a resultset and processes it through a DbRowProcessor.
 DbConnection getConnection()
          Obtains a DbConnection of this DbQueryManager's Datasource.
 Datasource getDatasource()
          Retrieves the Datasource of this DbQueryManager.
<ResultType>
ResultType
inTransaction(DbTransactionUser user)
          Ensures that all the instructions that are executed in the provided DbTransactionUser instance are executed inside a transaction and committed afterwards.
<ResultType>
ResultType
reserveConnection(DbConnectionUser user)
          Reserves a database connection for a this 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 Detail

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 Detail

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

DbQueryManager manager = new DbQueryManager(datasource);
int 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

DbQueryManager manager = new DbQueryManager(datasource);
Insert insert = new Insert(datasource);
insert.into("person").field("name", "me");
int 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,
                         DbPreparedStatementHandler handler)
                  throws DatabaseException
Safely execute an updates 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 DbPreparedStatementHandler.

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

DbQueryManager manager = new DbQueryManager(datasource);
Insert insert = new Insert(datasource);
insert.into("person").fieldParameter("name");
final String name = "me";
int count = manager.executeUpdate(insert, new DbPreparedStatementHandler() {
        public void setParameters(DbPreparedStatement statement)
        {
            statement
                .setString("name", name);
        }
    });

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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(), 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

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person");
boolean 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(), DbPreparedStatementHandler

executeHasResultRows

public boolean executeHasResultRows(ReadQuery query,
                                    DbPreparedStatementHandler 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 DbPreparedStatementHandler.

Example

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler that will be used to customize the query execution; or null if you don't want to customize it at all
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(), 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

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

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first String in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstString()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstString(), DbPreparedStatementHandler

executeGetFirstString

public String executeGetFirstString(ReadQuery query,
                                    DbPreparedStatementHandler 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 DbPreparedStatementHandler.

Example

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstString()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstString(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first boolean in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstBoolean()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstBoolean(), DbPreparedStatementHandler

executeGetFirstBoolean

public boolean executeGetFirstBoolean(ReadQuery query,
                                      DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstBoolean()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstBoolean(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first byte in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstByte()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstByte(), DbPreparedStatementHandler

executeGetFirstByte

public byte executeGetFirstByte(ReadQuery query,
                                DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstByte()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstByte(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first short in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstShort()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstShort(), DbPreparedStatementHandler

executeGetFirstShort

public short executeGetFirstShort(ReadQuery query,
                                  DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstShort()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstShort(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first int in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstInt()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstInt(), DbPreparedStatementHandler

executeGetFirstInt

public int executeGetFirstInt(ReadQuery query,
                              DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstInt()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstInt(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first long in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstLong()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstLong(), DbPreparedStatementHandler

executeGetFirstLong

public long executeGetFirstLong(ReadQuery query,
                                DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstLong()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstLong(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first float in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstFloat()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstFloat(), DbPreparedStatementHandler

executeGetFirstFloat

public float executeGetFirstFloat(ReadQuery query,
                                  DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstFloat()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstFloat(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first double in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstDouble()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstDouble(), DbPreparedStatementHandler

executeGetFirstDouble

public double executeGetFirstDouble(ReadQuery query,
                                    DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstDouble()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstDouble(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first byte array in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstBytes()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstBytes(), DbPreparedStatementHandler

executeGetFirstBytes

public byte[] executeGetFirstBytes(ReadQuery query,
                                   DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstBytes()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstBytes(), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first sql Date in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstDate()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstDate(), DbPreparedStatementHandler

executeGetFirstDate

public Date executeGetFirstDate(ReadQuery query,
                                DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstDate()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstDate(), 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% analogue.

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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstDate(Calendar)
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstDate(Calendar), DbPreparedStatementHandler

executeGetFirstDate

public Date executeGetFirstDate(ReadQuery query,
                                Calendar cal,
                                DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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 DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstDate(Calendar)
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstDate(Calendar), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first sql Time in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTime()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTime(), DbPreparedStatementHandler

executeGetFirstTime

public Time executeGetFirstTime(ReadQuery query,
                                DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTime()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTime(), 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% analogue.

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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTime(Calendar)
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTime(Calendar), DbPreparedStatementHandler

executeGetFirstTime

public Time executeGetFirstTime(ReadQuery query,
                                Calendar cal,
                                DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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 DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTime(Calendar)
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTime(Calendar), 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% analogue.

Parameters:
query - the query builder instance that needs to be executed
Returns:
the first sql Timestamp in the query's resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTimestamp()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTimestamp(), DbPreparedStatementHandler

executeGetFirstTimestamp

public Timestamp executeGetFirstTimestamp(ReadQuery query,
                                          DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTimestamp()
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTimestamp(), 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% analogue.

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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTimestamp(Calendar)
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTimestamp(Calendar), DbPreparedStatementHandler

executeGetFirstTimestamp

public Timestamp executeGetFirstTimestamp(ReadQuery query,
                                          Calendar cal,
                                          DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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 DbPreparedStatementHandler 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 resultset
Throws:
DatabaseException - see DbPreparedStatement.executeQuery()and DbResultSet.getFirstTimestamp(Calendar)
Since:
1.0
See Also:
DbPreparedStatement.executeQuery(), DbResultSet.getFirstTimestamp(Calendar), 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% analogue.

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(), DbPreparedStatementHandler

executeUseFirstAsciiStream

public <ResultType> ResultType executeUseFirstAsciiStream(ReadQuery query,
                                                          InputStreamUser user,
                                                          DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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 DbPreparedStatementHandler 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(), DbPreparedStatementHandler

executeUseFirstCharacterStream

public <ResultType> ResultType executeUseFirstCharacterStream(ReadQuery query,
                                                              ReaderUser user)
                                          throws DatabaseException,
                                                 InnerClassException
Safely and quickly retrieves the first cell as an 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% analogue.

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(), DbPreparedStatementHandler

executeUseFirstCharacterStream

public <ResultType> ResultType executeUseFirstCharacterStream(ReadQuery query,
                                                              ReaderUser user,
                                                              DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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 DbPreparedStatementHandler 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(), DbPreparedStatementHandler

executeUseFirstBinaryStream

public <ResultType> ResultType executeUseFirstBinaryStream(ReadQuery query,
                                                           InputStreamUser user)
                                       throws DatabaseException,
                                              InnerClassException
Safely and quickly retrieves the first cell as an 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% analogue.

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(), DbPreparedStatementHandler

executeUseFirstBinaryStream

public <ResultType> ResultType executeUseFirstBinaryStream(ReadQuery query,
                                                           InputStreamUser user,
                                                           DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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 DbPreparedStatementHandler 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(), 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

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").where("name", "=", "me");
DbRowProcessor processor = new YourProcessor();
boolean result = manager.executeFetchFirst(select, processor);

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,
                                 DbRowProcessor rowProcessor,
                                 DbPreparedStatementHandler 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 DbPreparedStatementHandler.

Example

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").whereParameter("name", "=");
DbRowProcessor processor = new YourProcessor();
final String name = "you";
boolean result = manager.executeFetchFirst(select, processor, new DbPreparedStatementHandler() {
        public void setParameters(DbPreparedStatement 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 DbPreparedStatementHandler 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

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

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

Parameters:
query - the query builder instance that needs to be executed
beanClass - the class of the bean
Returns:
true if a row was retrieved; or

false if there are no more rows .

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,
                                                 DbPreparedStatementHandler 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 DbPreparedStatementHandler.

Example

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").fields(Person.class).whereParameter("name", "=");
final String name = "you";
Person person = manager.executeFetchFirstBean(select, Person.class, new DbPreparedStatementHandler() {
        public void setParameters(DbPreparedStatement 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 DbPreparedStatementHandler 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 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

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").where("gender", "=", "m");
DbRowProcessor processor = new YourProcessor();
boolean result = manager.executeFetchAll(select, processor);

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,
                               DbRowProcessor rowProcessor,
                               DbPreparedStatementHandler 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 DbPreparedStatementHandler.

Example

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").whereParameter("gender", "=");
DbRowProcessor processor = new YourProcessor();
final String name = "m";
boolean result = manager.executeFetchAll(select, processor, new DbPreparedStatementHandler() {
        public void setParameters(DbPreparedStatement statement)
        {
            statement
                .setString("gender", 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 DbPreparedStatementHandler 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

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

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").fields(Person.class).where("gender", "=", "m");
List persons = 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,
                                                      DbPreparedStatementHandler 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 DbPreparedStatementHandler.

Example

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select.from("person").fields(Person.class).whereParameter("gender", "=");
final String name = "m";
List persons = manager.executeFetchAllBeans(select, Person.class, new DbPreparedStatementHandler() {
        public void setParameters(DbPreparedStatement statement)
        {
            statement
                .setString("gender", name);
        }
    });

Parameters:
query - the query builder instance that needs to be executed
beanClass - the class of the bean
handler - an instance of DbPreparedStatementHandler 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,
                                            DbPreparedStatementHandler 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 DbPreparedStatementHandler.

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

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

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

Parameters:
query - the query builder instance that needs to be executed
handler - an instance of DbPreparedStatementHandler 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(), DbPreparedStatementHandler

executeQuery

public <ResultType> ResultType executeQuery(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 resultset 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

DbQueryManager manager = new DbQueryManager(datasource);
Select select = new Select(datasource);
select
    .field("first")
    .field("last")
    .from("person");
String result = (String)manager.executeQuery(select, new DbResultSetHandler() {
        public Object concludeResults(DbResultSet resultset)
        throws SQLException
        {
            return resultset.getString("first")+" "+resultset.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 this 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 Insert store_data = new Insert(datasource).into("person").fields(person);
final Select get_last_id = new Select(datasource).from("person").field("LAST_INSERT_ID()");
final DbQueryManager 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(DbTransactionUser 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 an 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 Insert insert = new Insert(mDatasource).into("valuelist").field("value", 232);
final DbQueryManager manager = new DbQueryManager(datasource);
manager.inTransaction(new DbTransactionUserWithoutResult() {
        public void useTransactionWithoutResult()
        throws InnerClassException
        {
            manager.executeUpdate(insert);
            manager.executeUpdate(insert);
        }
    });

Parameters:
user - an instance of DbTransactionUser 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()

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 resultset.

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 resultset 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 resultset
Since:
1.0
See Also:
fetch(ResultSet, DbRowProcessor)

fetch

public boolean fetch(ResultSet resultSet,
                     DbRowProcessor rowProcessor)
              throws DatabaseException
Fetches the next row of a resultset 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 resultset
Since:
1.0
See Also:
fetch(ResultSet), DbRowProcessor

fetchAll

public boolean fetchAll(ResultSet resultSet,
                        DbRowProcessor rowProcessor)
                 throws DatabaseException
Fetches all the next rows of a resultset 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 resultset contained no rows.

Throws:
DatabaseException - when an error occurred during the fetch of the next rows in the resultset
Since:
1.0
See Also:
DbRowProcessor

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


Copyright © 2001-2007 Uwyn sprl/bvba. All Rights Reserved.