Class QueryRunner

  extended by 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.
  1. Create an instance of MappedStatement.
  2. As above, but no need to add any assemblers since they come from the statement itself.
  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);
        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.
      props = new java.util.Properties();
      conn = java.sql.DriverManager.getConnection("", 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, null);
      for(Iterator iter=ctx.iterateObjects(MyObject.class, MyObjectKey.class); iter.hasNext(); ) {
      // Read objects and print while reading, new BuildObjects.Sink() {
          public void built(Object obj, boolean isNew) {

@(#)$Revision: 1.6 $
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


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


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

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


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.

bld - the assembler to be added.


public void addAssemblers(Assembler[] blds)
Add multiple assemblers to this object.

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


public void reset()
Reset this object. This method clears out the list of assemblers.


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.

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.


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:


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


public void finalize()
finalize in class java.lang.Object


public void cleanUp()


public void iterateResultSet(QueryRunner.Observer sink)

Copyright © 2000 The Hydrate Project. All Rights Reserved.