org.apache.torque.util
Class BasePeer

java.lang.Object
  org.apache.torque.util.BasePeer

All Implemented Interfaces:

java.io.Serializable

public abstract class BasePeer
extends java.lang.Object
implements java.io.Serializable

This is the base class for all Peer classes in the system. Peer classes are responsible for isolating all of the database access for a specific business object. They execute all of the SQL against the database. Over time this class has grown to include utility methods which ease execution of cross-database queries and the implementation of concrete Peers.

Version:

$Id: BasePeer.java 750198 2009-03-04 22:34:43Z gmonroe $

Author:

Frank Y. Kim, John D. McNally, Brett McLaughlin, Stephen Haberman, Martin Poeschl, Augustin Vidovic, Henning P. Schmiedehausen

See Also:

Serialized Form

Nested Class Summary

protected static interface

BasePeer.ProcessCallback Inner Interface that defines the Callback method for the Record Processing

Field Summary

static java.lang.String	IGNORE_CASE Constant criteria key to remove Case Information from search/ordering criteria.
protected static org.apache.commons.logging.Log	log the log
static java.lang.String	ORDER_BY Constant criteria key to reference ORDER BY columns.
static java.lang.String	TABLE_NAME Classes that implement this class should override this value.

Constructor Summary

BasePeer()

Method Summary

static void	correctBooleans(Criteria criteria, TableMap defaultTableMap) Checks all columns in the criteria to see whether booleanchar and booleanint columns are queried with a boolean.
static void	createPreparedStatement(Criteria criteria, java.lang.StringBuffer queryString, java.util.List params) Create a new PreparedStatement.
static java.lang.String	createQueryString(Criteria criteria) Method to create an SQL query for actual execution based on values in a Criteria.
static void	deleteAll(java.sql.Connection con, java.lang.String table, java.lang.String column, int value) Convenience method that uses straight JDBC to delete multiple rows.
static void	deleteAll(java.lang.String table, java.lang.String column, int value) Convenience method that uses straight JDBC to delete multiple rows.
static void	doDelete(Criteria criteria) Deprecated. This method causes unexpected results when joins are used. Please use doDelete(Criteria, String).
static void	doDelete(Criteria criteria, java.sql.Connection con) Deprecated. This method causes unexpected results when joins are used. Please use doDelete(Criteria, String, Connection).
protected static void	doDelete(Criteria criteria, java.lang.String tableName) Method to perform deletes based on values and keys in a Criteria.
static void	doDelete(Criteria criteria, java.lang.String tableName, java.sql.Connection con) Method to perform deletes based on values and keys in a Criteria.
static ObjectKey	doInsert(Criteria criteria) Method to perform inserts based on values and keys in a Criteria.
static ObjectKey	doInsert(Criteria criteria, java.sql.Connection con) Method to perform inserts based on values and keys in a Criteria.
static java.util.List	doPSSelect(Criteria criteria) Do a Prepared Statement select according to the given criteria
static java.util.List	doPSSelect(Criteria criteria, java.sql.Connection con) Performs a SQL select using a PreparedStatement.
static java.util.List	doSelect(Criteria criteria) Returns all results.
static java.util.List	doSelect(Criteria criteria, java.sql.Connection con) Returns all results.
static void	doUpdate(Criteria updateValues) Convenience method used to update rows in the DB.
static void	doUpdate(Criteria updateValues, java.sql.Connection con) Convenience method used to update rows in the DB.
static void	doUpdate(Criteria selectCriteria, Criteria updateValues) Method used to update rows in the DB.
static void	doUpdate(Criteria criteria, Criteria updateValues, java.sql.Connection con) Method used to update rows in the DB.
static java.util.List	executeQuery(java.lang.String queryString) Utility method which executes a given sql statement.
static java.util.List	executeQuery(java.lang.String queryString, boolean singleRecord, java.sql.Connection con) Method for performing a SELECT.
static java.util.List	executeQuery(java.lang.String queryString, int start, int numberOfResults, boolean singleRecord, java.sql.Connection con) Method for performing a SELECT.
static java.util.List	executeQuery(java.lang.String queryString, int start, int numberOfResults, java.lang.String dbName, boolean singleRecord) Method for performing a SELECT.
static java.util.List	executeQuery(java.lang.String queryString, java.lang.String dbName) Utility method which executes a given sql statement.
static java.util.List	executeQuery(java.lang.String queryString, java.lang.String dbName, boolean singleRecord) Method for performing a SELECT.
static int	executeStatement(java.lang.String statementString) Utility method which executes a given sql statement.
static int	executeStatement(java.lang.String statementString, java.sql.Connection con) Utility method which executes a given sql statement.
static int	executeStatement(java.lang.String statementString, java.lang.String dbName) Utility method which executes a given sql statement.
static MapBuilder	getMapBuilder(java.lang.String name) Deprecated. Use Torque.getMapBuilder(name) instead
static java.util.List	getSelectResults(com.workingdogs.village.QueryDataSet qds) Returns all records in a QueryDataSet as a List of Record objects.
static java.util.List	getSelectResults(com.workingdogs.village.QueryDataSet qds, boolean singleRecord) Returns all records in a QueryDataSet as a List of Record objects.
static java.util.List	getSelectResults(com.workingdogs.village.QueryDataSet qds, int numberOfResults, boolean singleRecord) Returns numberOfResults records in a QueryDataSet as a List of Record objects.
static java.util.List	getSelectResults(com.workingdogs.village.QueryDataSet qds, int start, int numberOfResults, boolean singleRecord) Returns numberOfResults records in a QueryDataSet as a List of Record objects.
protected static void	handleMultipleRecords(com.workingdogs.village.DataSet ds) If the user specified that (s)he only wants to retrieve a single record and multiple records are retrieved, this method is called to handle the situation.
static java.lang.String[]	initColumnNames(com.workingdogs.village.Column[] columns) Convenience method to create a String array of column names.
static java.lang.String[]	initCriteriaKeys(java.lang.String tableName, java.lang.String[] columnNames) Convenience method to create a String array of criteria keys.
static com.workingdogs.village.Column[]	initTableColumns(com.workingdogs.village.Schema schema) Creates a Column array for a table based on its Schema.
static com.workingdogs.village.Schema	initTableSchema(java.lang.String tableName) Sets up a Schema for a table.
static com.workingdogs.village.Schema	initTableSchema(java.lang.String tableName, java.lang.String dbName) Sets up a Schema for a table.

Methods inherited from class java.lang.Object

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

Field Detail

ORDER_BY

public static final java.lang.String ORDER_BY

Constant criteria key to reference ORDER BY columns.

See Also:

Constant Field Values

IGNORE_CASE

public static final java.lang.String IGNORE_CASE

Constant criteria key to remove Case Information from search/ordering criteria.

See Also:

Constant Field Values

TABLE_NAME

public static final java.lang.String TABLE_NAME

Classes that implement this class should override this value.

See Also:

Constant Field Values

log

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

the log

Constructor Detail

BasePeer

public BasePeer()

Method Detail

initTableSchema

public static com.workingdogs.village.Schema initTableSchema(java.lang.String tableName)

Sets up a Schema for a table. This schema is then normally used as the argument for initTableColumns().

Parameters:

tableName - The name of the table.

Returns:

A Schema.

initTableSchema

public static com.workingdogs.village.Schema initTableSchema(java.lang.String tableName,
                                                             java.lang.String dbName)

Sets up a Schema for a table. This schema is then normally used as the argument for initTableColumns

Parameters:

tableName - The propery name for the database in the configuration file.

dbName - The name of the database.

Returns:

A Schema.

initTableColumns

public static com.workingdogs.village.Column[] initTableColumns(com.workingdogs.village.Schema schema)

Creates a Column array for a table based on its Schema.

Parameters:

schema - A Schema object.

Returns:

A Column[].

initColumnNames

public static java.lang.String[] initColumnNames(com.workingdogs.village.Column[] columns)

Convenience method to create a String array of column names.

Parameters:

columns - A Column[].

Returns:

A String[].

initCriteriaKeys

public static java.lang.String[] initCriteriaKeys(java.lang.String tableName,
                                                  java.lang.String[] columnNames)

Convenience method to create a String array of criteria keys.

Parameters:

tableName - Name of table.

columnNames - A String[].

Returns:

A String[].

deleteAll

public static void deleteAll(java.sql.Connection con,
                             java.lang.String table,
                             java.lang.String column,
                             int value)
                      throws TorqueException

Convenience method that uses straight JDBC to delete multiple rows. Village throws an Exception when multiple rows are deleted.

Parameters:

con - A Connection.

table - The table to delete records from.

column - The column in the where clause.

value - The value of the column.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

deleteAll

public static void deleteAll(java.lang.String table,
                             java.lang.String column,
                             int value)
                      throws TorqueException

Convenience method that uses straight JDBC to delete multiple rows. Village throws an Exception when multiple rows are deleted. This method attempts to get the default database from the pool.

Parameters:

table - The table to delete records from.

column - The column in the where clause.

value - The value of the column.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doDelete

public static void doDelete(Criteria criteria)
                     throws TorqueException

Deprecated. This method causes unexpected results when joins are used. Please use doDelete(Criteria, String).

Method to perform deletes based on values and keys in a Criteria.

Parameters:

criteria - The criteria to use.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doDelete

protected static void doDelete(Criteria criteria,
                               java.lang.String tableName)
                        throws TorqueException

Method to perform deletes based on values and keys in a Criteria. This method is protected because it may cause ambiguity between doDelete(Criteria,Connection) and this method. It will be made public once doDelete(Criteria, Connection) is removed.

Parameters:

criteria - The criteria to use.

tableName - the name of the table to delete records from. If set to null, the name of the table(s) can be extracted from the criteria, but this can cause unexpected results.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doDelete

public static void doDelete(Criteria criteria,
                            java.sql.Connection con)
                     throws TorqueException

Deprecated. This method causes unexpected results when joins are used. Please use doDelete(Criteria, String, Connection).

Method to perform deletes based on values and keys in a Criteria.

Parameters:

criteria - The criteria to use.

con - A Connection.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doDelete

public static void doDelete(Criteria criteria,
                            java.lang.String tableName,
                            java.sql.Connection con)
                     throws TorqueException

Method to perform deletes based on values and keys in a Criteria.

Parameters:

criteria - The criteria to use.

tableName - the name of the table to delete records from. If set to null, the name of the table(s) can be extracted from the criteria, but this can cause unexpected results.

con - A Connection.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doInsert

public static ObjectKey doInsert(Criteria criteria)
                          throws TorqueException

Method to perform inserts based on values and keys in a Criteria.

If the primary key is auto incremented the data in Criteria will be inserted and the auto increment value will be returned.

If the primary key is included in Criteria then that value will be used to insert the row.

If no primary key is included in Criteria then we will try to figure out the primary key from the database map and insert the row with the next available id using util.db.IDBroker.

If no primary key is defined for the table the values will be inserted as specified in Criteria and -1 will be returned.

Parameters:

criteria - Object containing values to insert.

Returns:

An Object which is the id of the row that was inserted (if the table has a primary key) or null (if the table does not have a primary key).

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doInsert

public static ObjectKey doInsert(Criteria criteria,
                                 java.sql.Connection con)
                          throws TorqueException

Method to perform inserts based on values and keys in a Criteria.

If the primary key is auto incremented the data in Criteria will be inserted and the auto increment value will be returned.

If the primary key is included in Criteria then that value will be used to insert the row.

If no primary key is included in Criteria then we will try to figure out the primary key from the database map and insert the row with the next available id using util.db.IDBroker.

If no primary key is defined for the table the values will be inserted as specified in Criteria and null will be returned.

Parameters:

criteria - Object containing values to insert.

con - A Connection.

Returns:

An Object which is the id of the row that was inserted (if the table has a primary key) or null (if the table does not have a primary key).

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

createQueryString

public static java.lang.String createQueryString(Criteria criteria)
                                          throws TorqueException

Method to create an SQL query for actual execution based on values in a Criteria.

Parameters:

criteria - A Criteria.

Returns:

the SQL query for actual execution

Throws:

TorqueException - Trouble creating the query string.

doSelect

public static java.util.List doSelect(Criteria criteria)
                               throws TorqueException

Returns all results.

Parameters:

criteria - A Criteria.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doSelect

public static java.util.List doSelect(Criteria criteria,
                                      java.sql.Connection con)
                               throws TorqueException

Returns all results.

Parameters:

criteria - A Criteria.

con - A Connection.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeQuery

public static java.util.List executeQuery(java.lang.String queryString)
                                   throws TorqueException

Utility method which executes a given sql statement. This method should be used for select statements only. Use executeStatement for update, insert, and delete operations.

Parameters:

queryString - A String with the sql statement to execute.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          java.lang.String dbName)
                                   throws TorqueException

Utility method which executes a given sql statement. This method should be used for select statements only. Use executeStatement for update, insert, and delete operations.

Parameters:

queryString - A String with the sql statement to execute.

dbName - The database to connect to.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          java.lang.String dbName,
                                          boolean singleRecord)
                                   throws TorqueException

Method for performing a SELECT. Returns all results.

Parameters:

queryString - A String with the sql statement to execute.

dbName - The database to connect to.

singleRecord - Whether or not we want to select only a single record.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          boolean singleRecord,
                                          java.sql.Connection con)
                                   throws TorqueException

Method for performing a SELECT. Returns all results.

Parameters:

queryString - A String with the sql statement to execute.

singleRecord - Whether or not we want to select only a single record.

con - A Connection.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          int start,
                                          int numberOfResults,
                                          java.lang.String dbName,
                                          boolean singleRecord)
                                   throws TorqueException

Method for performing a SELECT.

Parameters:

queryString - A String with the sql statement to execute.

start - The first row to return.

numberOfResults - The number of rows to return.

dbName - The database to connect to.

singleRecord - Whether or not we want to select only a single record.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          int start,
                                          int numberOfResults,
                                          boolean singleRecord,
                                          java.sql.Connection con)
                                   throws TorqueException

Method for performing a SELECT. Returns all results.

Parameters:

queryString - A String with the sql statement to execute.

start - The first row to return.

numberOfResults - The number of rows to return.

singleRecord - Whether or not we want to select only a single record.

con - A Connection.

Returns:

List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getSelectResults

public static java.util.List getSelectResults(com.workingdogs.village.QueryDataSet qds)
                                       throws TorqueException

Returns all records in a QueryDataSet as a List of Record objects. Used for functionality like util.LargeSelect.

Parameters:

qds - the QueryDataSet

Returns:

a List of Record objects

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

See Also:

getSelectResults(QueryDataSet, int, int, boolean)

getSelectResults

public static java.util.List getSelectResults(com.workingdogs.village.QueryDataSet qds,
                                              boolean singleRecord)
                                       throws TorqueException

Returns all records in a QueryDataSet as a List of Record objects. Used for functionality like util.LargeSelect.

Parameters:

qds - the QueryDataSet

singleRecord -

Returns:

a List of Record objects

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

See Also:

getSelectResults(QueryDataSet, int, int, boolean)

getSelectResults

public static java.util.List getSelectResults(com.workingdogs.village.QueryDataSet qds,
                                              int numberOfResults,
                                              boolean singleRecord)
                                       throws TorqueException

Returns numberOfResults records in a QueryDataSet as a List of Record objects. Starting at record 0. Used for functionality like util.LargeSelect.

Parameters:

qds - the QueryDataSet

numberOfResults -

singleRecord -

Returns:

a List of Record objects

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

See Also:

getSelectResults(QueryDataSet, int, int, boolean)

getSelectResults

public static java.util.List getSelectResults(com.workingdogs.village.QueryDataSet qds,
                                              int start,
                                              int numberOfResults,
                                              boolean singleRecord)
                                       throws TorqueException

Returns numberOfResults records in a QueryDataSet as a List of Record objects. Starting at record start. Used for functionality like util.LargeSelect.

Parameters:

qds - The QueryDataSet to extract results from.

start - The index from which to start retrieving Record objects from the data set.

numberOfResults - The number of results to return (or -1 for all results).

singleRecord - Whether or not we want to select only a single record.

Returns:

A List of Record objects.

Throws:

TorqueException - If any Exception occurs.

doUpdate

public static void doUpdate(Criteria updateValues)
                     throws TorqueException

Convenience method used to update rows in the DB. Checks if a single int primary key is specified in the Criteria object and uses it to perform the udpate. If no primary key is specified an Exception will be thrown.

Use this method for performing an update of the kind:

"WHERE primary_key_id = an int"

To perform an update with non-primary key fields in the WHERE clause use doUpdate(criteria, criteria).

Parameters:

updateValues - A Criteria object containing values used in set clause.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doUpdate

public static void doUpdate(Criteria updateValues,
                            java.sql.Connection con)
                     throws TorqueException

Convenience method used to update rows in the DB. Checks if a single int primary key is specified in the Criteria object and uses it to perform the udpate. If no primary key is specified an Exception will be thrown.

Use this method for performing an update of the kind:

"WHERE primary_key_id = an int"

To perform an update with non-primary key fields in the WHERE clause use doUpdate(criteria, criteria).

Parameters:

updateValues - A Criteria object containing values used in set clause.

con - A Connection.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doUpdate

public static void doUpdate(Criteria selectCriteria,
                            Criteria updateValues)
                     throws TorqueException

Method used to update rows in the DB. Rows are selected based on selectCriteria and updated using values in updateValues.

Use this method for performing an update of the kind:

WHERE some_column = some value AND could_have_another_column = another value AND so on...

Parameters:

selectCriteria - A Criteria object containing values used in where clause.

updateValues - A Criteria object containing values used in set clause.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

doUpdate

public static void doUpdate(Criteria criteria,
                            Criteria updateValues,
                            java.sql.Connection con)
                     throws TorqueException

Method used to update rows in the DB. Rows are selected based on criteria and updated using values in updateValues.

Use this method for performing an update of the kind:

WHERE some_column = some value AND could_have_another_column = another value AND so on.

Parameters:

criteria - A Criteria object containing values used in where clause.

updateValues - A Criteria object containing values used in set clause.

con - A Connection.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeStatement

public static int executeStatement(java.lang.String statementString)
                            throws TorqueException

Utility method which executes a given sql statement. This method should be used for update, insert, and delete statements. Use executeQuery() for selects.

Parameters:

statementString - A String with the sql statement to execute.

Returns:

The number of rows affected.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeStatement

public static int executeStatement(java.lang.String statementString,
                                   java.lang.String dbName)
                            throws TorqueException

Utility method which executes a given sql statement. This method should be used for update, insert, and delete statements. Use executeQuery() for selects.

Parameters:

statementString - A String with the sql statement to execute.

dbName - Name of database to connect to.

Returns:

The number of rows affected.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

executeStatement

public static int executeStatement(java.lang.String statementString,
                                   java.sql.Connection con)
                            throws TorqueException

Utility method which executes a given sql statement. This method should be used for update, insert, and delete statements. Use executeQuery() for selects.

Parameters:

statementString - A String with the sql statement to execute.

con - A Connection.

Returns:

The number of rows affected.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

handleMultipleRecords

protected static void handleMultipleRecords(com.workingdogs.village.DataSet ds)
                                     throws TooManyRowsException

If the user specified that (s)he only wants to retrieve a single record and multiple records are retrieved, this method is called to handle the situation. The default behavior is to throw an exception, but subclasses can override this method as needed.

Parameters:

ds - The DataSet which contains multiple records.

Throws:

TooManyRowsException - Couldn't handle multiple records.

getMapBuilder

public static MapBuilder getMapBuilder(java.lang.String name)
                                throws TorqueException

Deprecated. Use Torque.getMapBuilder(name) instead

This method returns the MapBuilder specified in the name parameter. You should pass in the full path to the class, ie: org.apache.torque.util.db.map.TurbineMapBuilder. The MapBuilder instances are cached in the TorqueInstance for speed.

Parameters:

name - name of the MapBuilder

Returns:

A MapBuilder, not null

Throws:

TorqueException - if the Map Builder cannot be instantiated

doPSSelect

public static java.util.List doPSSelect(Criteria criteria,
                                        java.sql.Connection con)
                                 throws TorqueException

Performs a SQL select using a PreparedStatement. Note: this method does not handle null criteria values.

Parameters:

criteria -

con -

Returns:

a List of Record objects.

Throws:

TorqueException - Error performing database query.

doPSSelect

public static java.util.List doPSSelect(Criteria criteria)
                                 throws TorqueException

Do a Prepared Statement select according to the given criteria

Parameters:

criteria -

Returns:

a List of Record objects.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

createPreparedStatement

public static void createPreparedStatement(Criteria criteria,
                                           java.lang.StringBuffer queryString,
                                           java.util.List params)
                                    throws TorqueException

Create a new PreparedStatement. It builds a string representation of a query and a list of PreparedStatement parameters.

Parameters:

criteria -

queryString -

params -

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

correctBooleans

public static void correctBooleans(Criteria criteria,
                                   TableMap defaultTableMap)
                            throws TorqueException

Checks all columns in the criteria to see whether booleanchar and booleanint columns are queried with a boolean. If yes, the query values are mapped onto values the database does understand, i.e. 0 and 1 for booleanints and N and Y for booleanchar columns.

Parameters:

criteria - The criteria to be checked for booleanint and booleanchar columns.

defaultTableMap - the table map to be used if the table name is not given in a column.

Throws:

TorqueException - if the database map for the criteria cannot be retrieved.