Java > Open Source Codes > org > apache > torque > util > BasePeer


1 package org.apache.torque.util;
2
3 /*
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  */
21
22 import java.io.Serializable ;
23 import java.sql.Connection ;
24 import java.sql.PreparedStatement ;
25 import java.sql.SQLException ;
26 import java.sql.Statement ;
27 import java.util.ArrayList ;
28 import java.util.Collections ;
29 import java.util.HashSet ;
30 import java.util.Iterator ;
31 import java.util.List ;
32 import java.util.Map ;
33 import java.util.Set ;
34
35 import org.apache.commons.lang.StringUtils;
36 import org.apache.commons.logging.Log;
37 import org.apache.commons.logging.LogFactory;
38 import org.apache.torque.Database;
39 import org.apache.torque.Torque;
40 import org.apache.torque.TorqueException;
41 import org.apache.torque.adapter.DB;
42 import org.apache.torque.map.ColumnMap;
43 import org.apache.torque.map.DatabaseMap;
44 import org.apache.torque.map.MapBuilder;
45 import org.apache.torque.map.TableMap;
46 import org.apache.torque.oid.IdGenerator;
47 import org.apache.torque.om.NumberKey;
48 import org.apache.torque.om.ObjectKey;
49 import org.apache.torque.om.SimpleKey;
50 import org.apache.torque.om.StringKey;
51
52 import com.workingdogs.village.Column;
53 import com.workingdogs.village.DataSet;
54 import com.workingdogs.village.DataSetException;
55 import com.workingdogs.village.KeyDef;
56 import com.workingdogs.village.QueryDataSet;
57 import com.workingdogs.village.Record;
58 import com.workingdogs.village.Schema;
59 import com.workingdogs.village.TableDataSet;
60
61 /**
62  * This is the base class for all Peer classes in the system. Peer
63  * classes are responsible for isolating all of the database access
64  * for a specific business object. They execute all of the SQL
65  * against the database. Over time this class has grown to include
66  * utility methods which ease execution of cross-database queries and
67  * the implementation of concrete Peers.
68  *
69  * @author <a HREF="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
70  * @author <a HREF="mailto:jmcnally@collab.net">John D. McNally</a>
71  * @author <a HREF="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
72  * @author <a HREF="mailto:stephenh@chase3000.com">Stephen Haberman</a>
73  * @author <a HREF="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
74  * @author <a HREF="mailto:vido@ldh.org">Augustin Vidovic</a>
75  * @author <a HREF="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
76  * @version $Id: BasePeer.java 493449 2007-01-06 11:46:50Z tv $
77  */
78 public abstract class BasePeer
79         implements Serializable
80 {
81     /** Constant criteria key to reference ORDER BY columns. */
82     public static final String ORDER_BY = "ORDER BY";
83
84     /**
85      * Constant criteria key to remove Case Information from
86      * search/ordering criteria.
87      */
88     public static final String IGNORE_CASE = "IgNOrE cAsE";
89
90     /** Classes that implement this class should override this value. */
91     public static final String TABLE_NAME = "TABLE_NAME";
92
93     /** the log */
94     protected static final Log log = LogFactory.getLog(BasePeer.class);
95
96     private static void throwTorqueException(Exception e)
97         throws TorqueException
98     {
99         if (e instanceof TorqueException)
100         {
101             throw (TorqueException) e;
102         }
103         else
104         {
105             throw new TorqueException(e);
106         }
107     }
108
109     /**
110      * Sets up a Schema for a table. This schema is then normally
111      * used as the argument for initTableColumns().
112      *
113      * @param tableName The name of the table.
114      * @return A Schema.
115      */
116     public static Schema initTableSchema(String tableName)
117     {
118         return initTableSchema(tableName, Torque.getDefaultDB());
119     }
120
121     /**
122      * Sets up a Schema for a table. This schema is then normally
123      * used as the argument for initTableColumns
124      *
125      * @param tableName The propery name for the database in the
126      * configuration file.
127      * @param dbName The name of the database.
128      * @return A Schema.
129      */
130     public static Schema initTableSchema(String tableName, String dbName)
131     {
132         Schema schema = null;
133         Connection con = null;
134
135         try
136         {
137             con = Torque.getConnection(dbName);
138             schema = new Schema().schema(con, tableName);
139         }
140         catch (Exception e)
141         {
142             log.error(e);
143             throw new Error ("Error in BasePeer.initTableSchema("
144                     + tableName
145                     + "): "
146                     + e.getMessage());
147         }
148         finally
149         {
150             Torque.closeConnection(con);
151         }
152         return schema;
153     }
154
155     /**
156      * Creates a Column array for a table based on its Schema.
157      *
158      * @param schema A Schema object.
159      * @return A Column[].
160      */
161     public static Column[] initTableColumns(Schema schema)
162     {
163         Column[] columns = null;
164         try
165         {
166             int numberOfColumns = schema.numberOfColumns();
167             columns = new Column[numberOfColumns];
168             for (int i = 0; i < numberOfColumns; i++)
169             {
170                 columns[i] = schema.column(i + 1);
171             }
172         }
173         catch (Exception e)
174         {
175             log.error(e);
176             throw new Error (
177                 "Error in BasePeer.initTableColumns(): " + e.getMessage());
178         }
179         return columns;
180     }
181
182     /**
183      * Convenience method to create a String array of column names.
184      *
185      * @param columns A Column[].
186      * @return A String[].
187      */
188     public static String [] initColumnNames(Column[] columns)
189     {
190         String [] columnNames = new String [columns.length];
191         for (int i = 0; i < columns.length; i++)
192         {
193             columnNames[i] = columns[i].name().toUpperCase();
194         }
195         return columnNames;
196     }
197
198     /**
199      * Convenience method to create a String array of criteria keys.
200      *
201      * @param tableName Name of table.
202      * @param columnNames A String[].
203      * @return A String[].
204      */
205     public static String [] initCriteriaKeys(
206         String tableName,
207         String [] columnNames)
208     {
209         String [] keys = new String [columnNames.length];
210         for (int i = 0; i < columnNames.length; i++)
211         {
212             keys[i] = tableName + "." + columnNames[i].toUpperCase();
213         }
214         return keys;
215     }
216
217     /**
218      * Convenience method that uses straight JDBC to delete multiple
219      * rows. Village throws an Exception when multiple rows are
220      * deleted.
221      *
222      * @param con A Connection.
223      * @param table The table to delete records from.
224      * @param column The column in the where clause.
225      * @param value The value of the column.
226      * @throws TorqueException Any exceptions caught during processing will be
227      * rethrown wrapped into a TorqueException.
228      */
229     public static void deleteAll(
230         Connection con,
231         String table,
232         String column,
233         int value)
234         throws TorqueException
235     {
236         Statement statement = null;
237         try
238         {
239             statement = con.createStatement();
240
241             StringBuffer query = new StringBuffer ();
242             query.append("DELETE FROM ")
243                 .append(table)
244                 .append(" WHERE ")
245                 .append(column)
246                 .append(" = ")
247                 .append(value);
248
249             statement.executeUpdate(query.toString());
250         }
251         catch (SQLException e)
252         {
253             throw new TorqueException(e);
254         }
255         finally
256         {
257             if (statement != null)
258             {
259                 try
260                 {
261                     statement.close();
262                 }
263                 catch (SQLException e)
264                 {
265                     throw new TorqueException(e);
266                 }
267             }
268         }
269     }
270
271     /**
272      * Convenience method that uses straight JDBC to delete multiple
273      * rows. Village throws an Exception when multiple rows are
274      * deleted. This method attempts to get the default database from
275      * the pool.
276      *
277      * @param table The table to delete records from.
278      * @param column The column in the where clause.
279      * @param value The value of the column.
280      * @throws TorqueException Any exceptions caught during processing will be
281      * rethrown wrapped into a TorqueException.
282      */
283     public static void deleteAll(String table, String column, int value)
284         throws TorqueException
285     {
286         Connection con = null;
287         try
288         {
289             // Get a connection to the db.
290 con = Torque.getConnection(Torque.getDefaultDB());
291             deleteAll(con, table, column, value);
292         }
293         finally
294         {
295             Torque.closeConnection(con);
296         }
297     }
298
299     /**
300      * Method to perform deletes based on values and keys in a
301      * Criteria.
302      *
303      * @param criteria The criteria to use.
304      * @throws TorqueException Any exceptions caught during processing will be
305      * rethrown wrapped into a TorqueException.
306      */
307     public static void doDelete(Criteria criteria) throws TorqueException
308     {
309         Connection con = null;
310         try
311         {
312             con = Transaction.beginOptional(
313                     criteria.getDbName(),
314                     criteria.isUseTransaction());
315             doDelete(criteria, con);
316             Transaction.commit(con);
317         }
318         catch (TorqueException e)
319         {
320             Transaction.safeRollback(con);
321             throw e;
322         }
323     }
324
325     /**
326      * Method to perform deletes based on values and keys in a Criteria.
327      *
328      * @param criteria The criteria to use.
329      * @param con A Connection.
330      * @throws TorqueException Any exceptions caught during processing will be
331      * rethrown wrapped into a TorqueException.
332      */
333     public static void doDelete(Criteria criteria, Connection con)
334         throws TorqueException
335     {
336         String dbName = criteria.getDbName();
337         final DatabaseMap dbMap = Torque.getDatabaseMap(dbName);
338
339         // This Callback adds all tables to the Table set which
340 // are referenced from a cascading criteria. As a result, all
341 // data that is referenced through foreign keys will also be
342 // deleted.
343 SQLBuilder.TableCallback tc = new SQLBuilder.TableCallback() {
344                 public void process (Set tables, String key, Criteria crit)
345                 {
346                     if (crit.isCascade())
347                     {
348                         // This steps thru all the columns in the database.
349 TableMap[] tableMaps = dbMap.getTables();
350                         for (int i = 0; i < tableMaps.length; i++)
351                         {
352                             ColumnMap[] columnMaps = tableMaps[i].getColumns();
353
354                             for (int j = 0; j < columnMaps.length; j++)
355                             {
356                                 // Only delete rows where the foreign key is
357 // also a primary key. Other rows need
358 // updating, but that is not implemented.
359 if (columnMaps[j].isForeignKey()
360                                         && columnMaps[j].isPrimaryKey()
361                                         && key.equals(columnMaps[j].getRelatedName()))
362                                 {
363                                     tables.add(tableMaps[i].getName());
364                                     crit.add(columnMaps[j].getFullyQualifiedName(),
365                                             crit.getValue(key));
366                                 }
367                             }
368                         }
369                     }
370                 }
371             };
372
373         Set tables = SQLBuilder.getTableSet(criteria, tc);
374
375         try
376         {
377             processTables(criteria, tables, con, new ProcessCallback() {
378                     public void process(String table, String dbName, Record rec)
379                         throws Exception
380                     {
381                         rec.markToBeDeleted();
382                         rec.save();
383                     }
384                 });
385         }
386         catch (Exception e)
387         {
388             throwTorqueException(e);
389         }
390     }
391
392     /**
393      * Method to perform inserts based on values and keys in a
394      * Criteria.
395      * <p>
396      * If the primary key is auto incremented the data in Criteria
397      * will be inserted and the auto increment value will be returned.
398      * <p>
399      * If the primary key is included in Criteria then that value will
400      * be used to insert the row.
401      * <p>
402      * If no primary key is included in Criteria then we will try to
403      * figure out the primary key from the database map and insert the
404      * row with the next available id using util.db.IDBroker.
405      * <p>
406      * If no primary key is defined for the table the values will be
407      * inserted as specified in Criteria and -1 will be returned.
408      *
409      * @param criteria Object containing values to insert.
410      * @return An Object which is the id of the row that was inserted
411      * (if the table has a primary key) or null (if the table does not
412      * have a primary key).
413      * @throws TorqueException Any exceptions caught during processing will be
414      * rethrown wrapped into a TorqueException.
415      */
416     public static ObjectKey doInsert(Criteria criteria) throws TorqueException
417     {
418         Connection con = null;
419         ObjectKey id = null;
420
421         try
422         {
423             con = Transaction.beginOptional(
424                     criteria.getDbName(),
425                     criteria.isUseTransaction());
426             id = doInsert(criteria, con);
427             Transaction.commit(con);
428         }
429         catch (TorqueException e)
430         {
431             Transaction.safeRollback(con);
432             throw e;
433         }
434
435         return id;
436     }
437
438     /**
439      * Method to perform inserts based on values and keys in a
440      * Criteria.
441      * <p>
442      * If the primary key is auto incremented the data in Criteria
443      * will be inserted and the auto increment value will be returned.
444      * <p>
445      * If the primary key is included in Criteria then that value will
446      * be used to insert the row.
447      * <p>
448      * If no primary key is included in Criteria then we will try to
449      * figure out the primary key from the database map and insert the
450      * row with the next available id using util.db.IDBroker.
451      * <p>
452      * If no primary key is defined for the table the values will be
453      * inserted as specified in Criteria and null will be returned.
454      *
455      * @param criteria Object containing values to insert.
456      * @param con A Connection.
457      * @return An Object which is the id of the row that was inserted
458      * (if the table has a primary key) or null (if the table does not
459      * have a primary key).
460      * @throws TorqueException Any exceptions caught during processing will be
461      * rethrown wrapped into a TorqueException.
462      */
463     public static ObjectKey doInsert(Criteria criteria, Connection con)
464         throws TorqueException
465     {
466         SimpleKey id = null;
467
468         // Get the table name and method for determining the primary
469 // key value.
470 String table = null;
471         Iterator keys = criteria.keySet().iterator();
472         if (keys.hasNext())
473         {
474             table = criteria.getTableName((String ) keys.next());
475         }
476         else
477         {
478             throw new TorqueException("Database insert attempted without "
479                     + "anything specified to insert");
480         }
481
482         String dbName = criteria.getDbName();
483         Database database = Torque.getDatabase(dbName);
484         DatabaseMap dbMap = database.getDatabaseMap();
485         TableMap tableMap = dbMap.getTable(table);
486         Object keyInfo = tableMap.getPrimaryKeyMethodInfo();
487         IdGenerator keyGen
488                 = database.getIdGenerator(tableMap.getPrimaryKeyMethod());
489
490         ColumnMap pk = getPrimaryKey(criteria);
491
492         // If the keyMethod is SEQUENCE or IDBROKERTABLE, get the id
493 // before the insert.
494 if (keyGen != null && keyGen.isPriorToInsert())
495         {
496             // pk will be null if there is no primary key defined for the table
497 // we're inserting into.
498 if (pk != null && !criteria.containsKey(pk.getFullyQualifiedName()))
499             {
500                 id = getId(pk, keyGen, con, keyInfo);
501                 criteria.add(pk.getFullyQualifiedName(), id);
502             }
503         }
504
505         // Use Village to perform the insert.
506 TableDataSet tds = null;
507         try
508         {
509             String tableName = SQLBuilder.getFullTableName(table, dbName);
510             tds = new TableDataSet(con, tableName);
511             Record rec = tds.addRecord();
512             // not the fully qualified name, insertOrUpdateRecord wants to use table as an index...
513 BasePeer.insertOrUpdateRecord(rec, table, dbName, criteria);
514         }
515         catch (DataSetException e)
516         {
517             throwTorqueException(e);
518         }
519         catch (SQLException e)
520         {
521             throwTorqueException(e);
522         }
523         catch (TorqueException e)
524         {
525             throwTorqueException(e);
526         }
527         finally
528         {
529             VillageUtils.close(tds);
530         }
531
532         // If the primary key column is auto-incremented, get the id
533 // now.
534 if (keyGen != null && keyGen.isPostInsert())
535         {
536             id = getId(pk, keyGen, con, keyInfo);
537         }
538
539         return id;
540     }
541
542     /**
543      * Create an Id for insertion in the Criteria
544      *
545      * @param pk ColumnMap for the Primary key
546      * @param keyGen The Id Generator object
547      * @param con The SQL Connection to run the id generation under
548      * @param keyInfo KeyInfo Parameter from the Table map
549      *
550      * @return A simple Key representing the new Id value
551      * @throws TorqueException Possible errors get wrapped in here.
552      */
553     private static SimpleKey getId(ColumnMap pk, IdGenerator keyGen, Connection con, Object keyInfo)
554             throws TorqueException
555     {
556         SimpleKey id = null;
557
558         try
559         {
560             if (pk != null && keyGen != null)
561             {
562                 if (pk.getType() instanceof Number )
563                 {
564                     id = new NumberKey(
565                             keyGen.getIdAsBigDecimal(con, keyInfo));
566                 }
567                 else
568                 {
569                     id = new StringKey(keyGen.getIdAsString(con, keyInfo));
570                 }
571             }
572         }
573         catch (Exception e)
574         {
575             throwTorqueException(e);
576         }
577         return id;
578     }
579
580     /**
581      * Grouping of code used in both doInsert() and doUpdate()
582      * methods. Sets up a Record for saving.
583      *
584      * @param rec A Record.
585      * @param table Name of table.
586      * @param criteria A Criteria.
587      * @throws TorqueException Any exceptions caught during processing will be
588      * rethrown wrapped into a TorqueException.
589      */
590     private static void insertOrUpdateRecord(
591         Record rec,
592         String table,
593         String dbName,
594         Criteria criteria)
595         throws TorqueException
596     {
597         DatabaseMap dbMap = Torque.getDatabaseMap(dbName);
598
599         ColumnMap[] columnMaps = dbMap.getTable(table).getColumns();
600         boolean shouldSave = false;
601         for (int j = 0; j < columnMaps.length; j++)
602         {
603             ColumnMap colMap = columnMaps[j];
604             String colName = colMap.getColumnName();
605             String key = new StringBuffer (colMap.getTableName())
606                     .append('.')
607                     .append(colName)
608                     .toString();
609             if (criteria.containsKey(key))
610             {
611                 try
612                 {
613                     VillageUtils.setVillageValue(criteria, key, rec, colName);
614                     shouldSave = true;
615                 }
616                 catch (Exception e)
617                 {
618                     throwTorqueException(e);
619                 }
620             }
621         }
622
623         if (shouldSave)
624         {
625             try
626             {
627                 rec.save();
628             }
629             catch (Exception e)
630             {
631                 throwTorqueException(e);
632             }
633         }
634         else
635         {
636             throw new TorqueException("No changes to save");
637         }
638     }
639
640     /**
641      * Method to create an SQL query for display only based on values in a
642      * Criteria.
643      *
644      * @param criteria A Criteria.
645      * @return the SQL query for display
646      * @exception TorqueException Trouble creating the query string.
647      */
648     static String createQueryDisplayString(Criteria criteria)
649         throws TorqueException
650     {
651         return createQuery(criteria).toString();
652     }
653
654     /**
655      * Method to create an SQL query for actual execution based on values in a
656      * Criteria.
657      *
658      * @param criteria A Criteria.
659      * @return the SQL query for actual execution
660      * @exception TorqueException Trouble creating the query string.
661      */
662     public static String createQueryString(Criteria criteria)
663         throws TorqueException
664     {
665         Query query = createQuery(criteria);
666         return query.toString();
667     }
668
669     /**
670      * Method to create an SQL query based on values in a Criteria. Note that
671      * final manipulation of the limit and offset are performed when the query
672      * is actually executed.
673      *
674      * @param criteria A Criteria.
675      * @return the sql query
676      * @exception TorqueException Trouble creating the query string.
677      */
678     static Query createQuery(Criteria criteria)
679         throws TorqueException
680     {
681         return SQLBuilder.buildQueryClause(criteria, null, new SQLBuilder.QueryCallback() {
682                 public String process(Criteria.Criterion criterion, List params)
683                 {
684                     return criterion.toString();
685                 }
686             });
687     }
688
689     /**
690      * Returns all results.
691      *
692      * @param criteria A Criteria.
693      * @return List of Record objects.
694      * @throws TorqueException Any exceptions caught during processing will be
695      * rethrown wrapped into a TorqueException.
696      */
697     public static List doSelect(Criteria criteria) throws TorqueException
698     {
699         Connection con = null;
700         List results = null;
701
702         try
703         {
704             con = Transaction.beginOptional(
705                     criteria.getDbName(),
706                     criteria.isUseTransaction());
707             results = doSelect(criteria, con);
708             Transaction.commit(con);
709         }
710         catch (TorqueException e)
711         {
712             Transaction.safeRollback(con);
713             throw e;
714         }
715         return results;
716     }
717
718     /**
719      * Returns all results.
720      *
721      * @param criteria A Criteria.
722      * @param con A Connection.
723      * @return List of Record objects.
724      * @throws TorqueException Any exceptions caught during processing will be
725      * rethrown wrapped into a TorqueException.
726      */
727     public static List doSelect(Criteria criteria, Connection con)
728         throws TorqueException
729     {
730         Query query = createQuery(criteria);
731         DB dbadapter = Torque.getDB(criteria.getDbName());
732
733         // Call Village depending on the capabilities of the DB
734 return executeQuery(query.toString(),
735                 dbadapter.supportsNativeOffset() ? 0 : criteria.getOffset(),
736                 dbadapter.supportsNativeLimit() ? -1 : criteria.getLimit(),
737                 criteria.isSingleRecord(),
738                 con);
739     }
740
741     /**
742      * Utility method which executes a given sql statement. This
743      * method should be used for select statements only. Use
744      * executeStatement for update, insert, and delete operations.
745      *
746      * @param queryString A String with the sql statement to execute.
747      * @return List of Record objects.
748      * @throws TorqueException Any exceptions caught during processing will be
749      * rethrown wrapped into a TorqueException.
750      */
751     public static List executeQuery(String queryString) throws TorqueException
752     {
753         return executeQuery(queryString, Torque.getDefaultDB(), false);
754     }
755
756     /**
757      * Utility method which executes a given sql statement. This
758      * method should be used for select statements only. Use
759      * executeStatement for update, insert, and delete operations.
760      *
761      * @param queryString A String with the sql statement to execute.
762      * @param dbName The database to connect to.
763      * @return List of Record objects.
764      * @throws TorqueException Any exceptions caught during processing will be
765      * rethrown wrapped into a TorqueException.
766      */
767     public static List executeQuery(String queryString, String dbName)
768         throws TorqueException
769     {
770         return executeQuery(queryString, dbName, false);
771     }
772
773     /**
774      * Method for performing a SELECT. Returns all results.
775      *
776      * @param queryString A String with the sql statement to execute.
777      * @param dbName The database to connect to.
778      * @param singleRecord Whether or not we want to select only a
779      * single record.
780      * @return List of Record objects.
781      * @throws TorqueException Any exceptions caught during processing will be
782      * rethrown wrapped into a TorqueException.
783      */
784     public static List executeQuery(
785         String queryString,
786         String dbName,
787         boolean singleRecord)
788         throws TorqueException
789     {
790         return executeQuery(queryString, 0, -1, dbName, singleRecord);
791     }
792
793     /**
794      * Method for performing a SELECT. Returns all results.
795      *
796      * @param queryString A String with the sql statement to execute.
797      * @param singleRecord Whether or not we want to select only a
798      * single record.
799      * @param con A Connection.
800      * @return List of Record objects.
801      * @throws TorqueException Any exceptions caught during processing will be
802      * rethrown wrapped into a TorqueException.
803      */
804     public static List executeQuery(
805         String queryString,
806         boolean singleRecord,
807         Connection con)
808         throws TorqueException
809     {
810         return executeQuery(queryString, 0, -1, singleRecord, con);
811     }
812
813     /**
814      * Method for performing a SELECT.
815      *
816      * @param queryString A String with the sql statement to execute.
817      * @param start The first row to return.
818      * @param numberOfResults The number of rows to return.
819      * @param dbName The database to connect to.
820      * @param singleRecord Whether or not we want to select only a
821      * single record.
822      * @return List of Record objects.
823      * @throws TorqueException Any exceptions caught during processing will be
824      * rethrown wrapped into a TorqueException.
825      */
826     public static List executeQuery(
827         String queryString,
828         int start,
829         int numberOfResults,
830         String dbName,
831         boolean singleRecord)
832         throws TorqueException
833     {
834         Connection con = null;
835         List results = null;
836         try
837         {
838             con = Torque.getConnection(dbName);
839             // execute the query
840 results = executeQuery(
841                     queryString,
842                     start,
843             &nb