com.townleyenterprises.persistence
Class QueryHandler

java.lang.Object
  com.townleyenterprises.persistence.QueryHandler

public class QueryHandler

extends java.lang.Object

This class encapsulates the core functionality of making a database query into a single place. Queries are executed based on the settings of certain properties for the class, and listeners may be registered to receive notification of each row to be processed.

Migration from Earlier Releases

Prior to version 2.1, this class relied on a pre-release version of Jaxor being available to perform tasks such as setting the query parameters and supplying connections. With version 2.1, this link is no longer present, however the previous behavior is available by placing one of the appropriate extensions in the classpath prior to the main te-common.jar.

Version:

$Id: QueryHandler.java,v 1.5 2004/07/28 10:33:59 atownley Exp $

Author:

Andrew S. Townley

Constructor Summary

QueryHandler()
The constructure allocates a new set of resources for executing a specific query.

QueryHandler(ConnectionFactory factory)
This constructor allows setting a connection factory for this instance.

Method Summary

void	abort() This method causes the query handler to abort processing the active query.
void	addQueryListener(QueryListener listener) This method adds a QueryListener to the list of objects which will retrieve notifications of various QueryHandler events.
void	execute(java.lang.String query, java.lang.Object[] params) This method actually executes the query based on the configured property values and the query and query parameters.
protected void	nextRow(QueryEvent event) This method is called by the QueryHandler after notifiying the listeners of the next row.
void	removeQueryListener(QueryListener listener) This method is used to unregister an object from the list of listeners.
void	setConnectionFactory(ConnectionFactory factory) This method initializes the connection factory for this instance.
static void	setDefaultConnectionFactory(ConnectionFactory factory) This method is used to set the default conneciton factory for all instances of this class
void	setStart(int start) This method sets the start row for processing the results.

Methods inherited from class java.lang.Object

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

Constructor Detail

QueryHandler

public QueryHandler()

The constructure allocates a new set of resources for executing a specific query.

QueryHandler

public QueryHandler(ConnectionFactory factory)

This constructor allows setting a connection factory for this instance.

Parameters:

factory - the connection factory to use

Since:

2.1

Method Detail

abort

public void abort()

This method causes the query handler to abort processing the active query.

addQueryListener

public void addQueryListener(QueryListener listener)

This method adds a QueryListener to the list of objects which will retrieve notifications of various QueryHandler events.

Parameters:

listener - the QueryListener

execute

public void execute(java.lang.String query,
                    java.lang.Object[] params)
             throws java.sql.SQLException

This method actually executes the query based on the configured property values and the query and query parameters. For each row in the result set, each registered listener is notified so that they may do whatever is necessary (create an object for the row, or generate a summary report, or whatever)

NOTE: this code is borrowed almost exactly from Jaxor's BaseFinder.executeQuery method.

Parameters:

query - the SQL query to be executed

params - the parameters to be supplied to the query

Returns:

a List containing the results. In the event that there are not count number of rows, only the specific rows will be retrieved. If there are less rows than the start index, an empty list will be returned.

Throws:

java.sql.SQLException - if an SQLException was thrown during query execution

removeQueryListener

public void removeQueryListener(QueryListener listener)

This method is used to unregister an object from the list of listeners. If the listener is not registered, no error is raised.

Parameters:

listener - the QueryLister

setConnectionFactory

public void setConnectionFactory(ConnectionFactory factory)

This method initializes the connection factory for this instance. This factory will be used instead of attempting to obtain a connection from the JaxorSession.

Parameters:

factory - the ConnectionFactory instance

setStart

public void setStart(int start)

This method sets the start row for processing the results.

nextRow

protected void nextRow(QueryEvent event)
                throws java.sql.SQLException

This method is called by the QueryHandler after notifiying the listeners of the next row.

Parameters:

event - the QueryEvent to propagate

Throws:

java.sql.SQLException - if there is an issue with processing the result set

setDefaultConnectionFactory

public static void setDefaultConnectionFactory(ConnectionFactory factory)

This method is used to set the default conneciton factory for all instances of this class

Parameters:

factory - the factory