org.hydrateframework
Class QueryRunner

java.lang.Object
  org.hydrateframework.QueryRunner

public class QueryRunner
extends java.lang.Object

This class orchestrates the loading of objects through the Hydrate framework. In order to build objects from a data source in Hydrate, a client must do the following:

1. Create and execute a query, returning a ResultSet object. Generally, an instance of NamedParameterStatement or one of its derivatives will be used as the query, and this is a requirement when using this class.
2. Create a Assembler object for each kind of object that will be constructed from the results. If the statement is a MappedStatement then the list of assemblers comes from this statement.
3. Prepare each assembler with the result set from the first step.
4. Iterate through the rows of the result set - for each row:
5. Reset each assembler by calling startNewRow(...)
6. Try to build an object off each assembler by calling buildOneObject
7. Optionally do some operation on each built object

All of these steps are carried out by this class. The class is used as follows:

1. Create an instance of NamedParameterStatement.
2. Create one assembler for each object to be built. Add to the BuildObjects object with the addAssembler(org.hydrateframework.Assembler) or addAssemblers(org.hydrateframework.Assembler[]) methods.
3. Optionally create an instance of QueryRunner.Observer that will receive notification of objects as they are built.
4. Call the #build(java.sql.PreparedStatement, BuildObjects.Sink) method to run the query and build all objects from it.

or

1. Create an instance of MappedStatement.
2. As above, but no need to add any assemblers since they come from the statement itself.

or

1. Optionally create an instance of QueryRunner.Observer that will receive notification of objects as they are built.
2. Call the #build(RequestContext, Assembler, Constraint, java.lang.String, BuildObjects.Sink) method to build objects of the type implied by the supplied assembler, using the query and database configured in the installed ObjectFactory for that object.

For example:

      // The object context contains knowledge about the object model
      // you created.  Configure it with YourGeneratedModelClass.configureContext(..)  
         final ObjectContext ctx = new ObjectContext(true);
        MyModel.configureContext(ctx);
        RequestContext rc = new RequestContext(ctx);
        
      // Create the query set a parameter and read objects into memory
      QueryMap queryMap = new QueryMap(ctx, "MyQuery.xml");
              
      // Create a connection - we could get from a pool if we were on a server.
      Class.forName("com.mydb.MyDbDriver");
      props = new java.util.Properties();
      conn = java.sql.DriverManager.getConnection("jdbc:mydb:myserver.mydomain.com", props);
      rc.addConnection("jdbc/TEST", conn);
        
      queryMap.setString("date", new Date());
      queryMap.setString("name", "Test");
        
      QueryRunner qr = new QueryRunner(ctx);
 
      // Read objects and print when read
      qr.build(queryMap, null);
      for(Iterator iter=ctx.iterateObjects(MyObject.class, MyObjectKey.class); iter.hasNext(); ) {
          System.out.println(iter.next().toString());
      }
       
      // Read objects and print while reading 
      qr.build(queryMap, new BuildObjects.Sink() {
          public void built(Object obj, boolean isNew) {
              System.out.println(obj.toString());
          }
      });
 

Version:

@(#)$Revision: 1.6 $

Author:

David Chamberlin

Nested Class Summary

static class	QueryRunner.GetSingleObject This is a BuildObjects callback interface that retrieves a single object of a particular type from a query.
static interface	QueryRunner.Observer This interface should be supported by objects that require notification of the construction of objects as they are loaded from the data source.
static class	QueryRunner.SaveNew

Field Summary

protected static org.apache.commons.logging.Log

m_log

Constructor Summary

QueryRunner(ObjectContext ctx)
A BuildObjects class is always tied to a single ObjectContext.

Method Summary

void	addAssembler(Assembler bld) Add a assembler to this object.
void	addAssemblers(Assembler[] blds) Add multiple assemblers to this object.
void	build(java.sql.Connection conn, java.lang.String sql, QueryRunner.Observer sink)
void	build(java.sql.PreparedStatement stmt, QueryRunner.Observer sink) Build objects from a query.
void	build(RequestContext rc, Assembler bld, Constraint qd, java.lang.String prmNm, QueryRunner.Observer sink) Build objects using the installed object factory.
void	cleanUp()
void	finalize()
void	iterateResultSet(QueryRunner.Observer sink)
void	reset() Reset this object.

Methods inherited from class java.lang.Object

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

Field Detail

m_log

protected static final org.apache.commons.logging.Log m_log

Constructor Detail

QueryRunner

public QueryRunner(ObjectContext ctx)

A BuildObjects class is always tied to a single ObjectContext.

Parameters:

ctx - the object context associated with the new object instance.

Method Detail

addAssembler

public void addAssembler(Assembler bld)

Add a assembler to this object. When the #build(java.sql.PreparedStatement, BuildObjects.Sink) method is called, this object will attempt to build an object for each assembler that was added using this method.

Parameters:

bld - the assembler to be added.

addAssemblers

public void addAssemblers(Assembler[] blds)

Add multiple assemblers to this object.

Parameters:

blds - the list of assemblers (an array) to be added.

See Also:

addAssembler(Assembler)

reset

public void reset()

Reset this object. This method clears out the list of assemblers.

build

public void build(RequestContext rc,
                  Assembler bld,
                  Constraint qd,
                  java.lang.String prmNm,
                  QueryRunner.Observer sink)
           throws SaveException

Build objects using the installed object factory. This method will build objects of a single type from the data source implied by the installed object factory for that class.

Parameters:

rc - the request context that contains request-scoped information.

bld - the assembler to use. This also implies which object will be built.

qd - the constraint to apply to the query. This could be an instance of one of the object's keys, or any other restriction to be applied to the default query.

prmNm - the constraint parameter name.

sink - a callback interface to receive notifications of objects as they are created.

Throws:

SaveException

build

public void build(java.sql.PreparedStatement stmt,
                  QueryRunner.Observer sink)
           throws SaveException

Build objects from a query. Unless the query is an instance of MappedStatement, the client must have added some assemblers to this class, in order for this method to build anything. This method performs the following steps:

• Sets the list of assemblers for the query, if the query was a MappedStatement
• Executes the supplied statement
• Prepares all of the assemblers by calling Assembler.prepareToProcessResults(java.sql.ResultSet, java.sql.Statement, boolean) on each assembler in turn
• Steps through the results set that was the result of the query and for each row trys to build an object for each assembler.

  Parameters:

  stmt - the query to run to get the result set from which objects are to be built.

  sink - a callback interface to receive notifications of objects as they are created.

  Throws:

  SaveException

build

public void build(java.sql.Connection conn,
                  java.lang.String sql,
                  QueryRunner.Observer sink)
           throws SaveException

Throws:

SaveException

finalize

public void finalize()

Overrides:

finalize in class java.lang.Object

cleanUp

public void cleanUp()

iterateResultSet

public void iterateResultSet(QueryRunner.Observer sink)