com.boylesoftware.cb2
Interface FetchExecutor

All Superinterfaces:

DAOPlugin

All Known Implementing Classes:

GenericFetchExecutor

public interface FetchExecutor

extends DAOPlugin

Interface for modules that are used by the DAO's fetch calls to prepare and execute SQL statements.

A custom imlpementation of FetchExecutor can be installed to the DAO as a DAO plugin. Only one such plugin is allowed for a DAO. By default, if no custom FetchExecutor plugin is installed, the DAO uses GenericFetchExecutor.

Unlike many other DAO plugin types, the DAO does not allow concurrent threads into the same instance of the fetch executor. Also, the fetch executor can be stateful - the DAO guarantees that single instance will be used during one fetch call.

Here is the protocol of how the DAO calls the fetch executor:

1. When a fetch method is called on the DAO, an instance of the currently configured for this DAO FetchExecutor implementation ( GenericFetchExecutor by default) is taken from the pool. Then the init method is called on it and the fetch call parameters are passed to it so it can initialize its internals.
2. The prepareStatement is called and it returns the java.sql.Statement object to be executed by the DAO. If there are query parameters, then the method must return an instance of java.sql.PreparedStatement, so the DAO can set the parameters on it.
3. If there are query parameters, the DAO sets them on the statement returned by the previous call. The fetch executor is not involved in this process (but QueryParamProcessor and QueryParamSetter plugins are, if defined for the DAO).
4. The execute is called and the fetch executor actually executes the query, which returnes a result set. The result set is stored then internally in the fetch executor.
5. Immediately, the getResultSet is called and it returns a reference to the just fetched result set.
6. setToTheFirstRow is called.
7. If the previous call returned true, then the DAO processes the result set rows, and, when it is finished, it calls finish method on the fetch executor. Otherwise, if the setToTheFirstRow call returned false, this step is skipped and the finish method is never called.
8. Finally, destroy method is called and the fetch executor instance is returned back to the pool. Note, that the destroy method gets called always, even if there were exceptions thrown by other methods.

Version:

$Id: FetchExecutor.java,v 1.2 2004/04/20 16:00:58 levahim Exp $

Author:

Lev Himmelfarb

See Also:

DAO.fetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)

Method Summary

void	destroy() Releases any used resources, but does not close any exposed to the DAO database resources like the result set, the statement returned by the execute method and the connection.
java.sql.Statement	execute() Executes the query and returns the statement, which was actually used for getting the result set (possibly a different statement from what prepareStatement returned).
void	finish(int nRowsProcessed, java.util.List result) Called after everything has been processed and the resulting array of DMs formed.
java.sql.ResultSet	getResultSet() Gets the result set after execute method call.
void	init(DAOConfig daoConfig, java.sql.Connection con, java.lang.Class dmClass, java.lang.String query, java.lang.Object[] queryParams, int page, int pageSize, FetchResultDescriptor fetchResultDescriptor) Initializes the executor before calling any other methods.
java.sql.Statement	prepareStatement() Prepares a statement object before the execute method call.
boolean	setToTheFirstRow() Positions the result set cursor to the first row of the requested data.

Methods inherited from interface com.boylesoftware.cb2.DAOPlugin

setApplicationContext

Method Detail

init

public void init(DAOConfig daoConfig,
                 java.sql.Connection con,
                 java.lang.Class dmClass,
                 java.lang.String query,
                 java.lang.Object[] queryParams,
                 int page,
                 int pageSize,
                 FetchResultDescriptor fetchResultDescriptor)
          throws java.sql.SQLException

Initializes the executor before calling any other methods.

Parameters:

daoConfig - the DAO configuration.

con - the database connection to be used.

dmClass - class of the top-level DMs to be returned by the call.

query - the SQL query text.

queryParams - values for the query parameters, null or empty array if the query needs no parameters.

page - number of the result set page requested, starting from zero.

pageSize - number of records in one result set page, equal or less than zero if result set pagination is not requested.

fetchResultDescriptor - the FetchResultDescriptor instance or null if no result info requested.

Throws:

java.sql.SQLException - if the executor cannot be initialized.

prepareStatement

public java.sql.Statement prepareStatement()
                                    throws java.sql.SQLException

Prepares a statement object before the execute method call. Note, that if the query requires parameters, that is the queryParams passed to the init method was not null and not empty, then this method is required to return an instance of java.sql.PreparedStatement, so the DAO can set query parameters on it before calling execute.

Returns:

the statement object, which may be an instance of java.sql.PreparedStatement.

Throws:

java.sql.SQLException - if a database error happens.

execute

public java.sql.Statement execute()
                           throws java.sql.SQLException

Executes the query and returns the statement, which was actually used for getting the result set (possibly a different statement from what prepareStatement returned). The getResultSet method is called later to retrieve the result set.

Returns:

the statement owning the result set.

Throws:

java.sql.SQLException - if a database error happens.

getResultSet

public java.sql.ResultSet getResultSet()

Gets the result set after execute method call.

Returns:

result set with the requested data.

setToTheFirstRow

public boolean setToTheFirstRow()
                         throws java.sql.SQLException

Positions the result set cursor to the first row of the requested data.

Returns:

true if the cursor has been set or false if there is not data (for example the result set is empty or the requested page does not exist).

Throws:

java.sql.SQLException - if a database error happens.

finish

public void finish(int nRowsProcessed,
                   java.util.List result)
            throws java.sql.SQLException

Called after everything has been processed and the resulting array of DMs formed. This method does not get called if the setToTheFirstRow returned false.

Parameters:

nRowsProcessed - number of result set rows processed by the DAO.

result - the result, which will be returned by the DAO to the caller as a java.util.List of DMs.

Throws:

java.sql.SQLException - if a database error happens.

destroy

public void destroy()

Releases any used resources, but does not close any exposed to the DAO database resources like the result set, the statement returned by the execute method and the connection.