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,v 1.39 2002/05/07 05:57:19 dobbs Exp $

Author:

Frank Y. Kim, John D. McNally, Brett McLaughlin

See Also:

Serialized Form

Field Summary

protected static org.apache.log4j.Category	category
static java.lang.String	DEFAULT_MAP_BUILDER The Turbine default MapBuilder.
static java.lang.String	IGNORE_CASE Constant criteria key to remove Case Information from search/ordering criteria.
private static java.util.Hashtable	mapBuilders Hashtable that contains the cached mapBuilders.
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 DBConnection	beginTransaction(java.lang.String dbName) Begin a transaction.
static void	commitTransaction(DBConnection dbCon) Commit a transaction.
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 based on values in a Criteria.
static void	deleteAll(DBConnection dbCon, 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) Method to perform deletes based on values and keys in a Criteria.
static void	doDelete(Criteria criteria, DBConnection dbCon) 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, DBConnection dbCon) 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, DBConnection dbCon) Performs a SQL select using a PreparedStatement.
static java.util.List	doSelect(Criteria criteria) Returns all results.
static java.util.List	doSelect(Criteria criteria, DBConnection dbCon) Returns all results.
static void	doUpdate(Criteria updateValues) 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 selectCriteria, Criteria updateValues, DBConnection dbCon) Method used to update rows in the DB.
static void	doUpdate(Criteria updateValues, DBConnection dbCon) Convenience 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, DBConnection dbCon) Method for performing a SELECT.
static java.util.List	executeQuery(java.lang.String queryString, int start, int numberOfResults, boolean singleRecord, DBConnection dbCon) 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 stmt) Utility method which executes a given sql statement.
static int	executeStatement(java.lang.String stmt, DBConnection dbCon) Utility method which executes a given sql statement.
static int	executeStatement(java.lang.String stmt, java.lang.String dbName) Utility method which executes a given sql statement.
static MapBuilder	getMapBuilder() This method returns the MapBuilder specified in the TurbineResources.properties file.
static MapBuilder	getMapBuilder(java.lang.String name) This method returns the MapBuilder specified in the name parameter.
private static ColumnMap	getPrimaryKey(Criteria criteria) Helper method which returns the primary key contained in the given Criteria object.
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	handleMultiple(com.workingdogs.village.DataSet ds) Deprecated. Use the better-named handleMultipleRecords() instead.
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 byte[]	hashtableToByteArray(java.util.Hashtable hash) Converts a hashtable to a byte array for storage/serialization.
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.
private static void	insertOrUpdateRecord(com.workingdogs.village.Record rec, java.lang.String tableName, Criteria criteria) Grouping of code used in both doInsert() and doUpdate() methods.
static void	rollBackTransaction(DBConnection dbCon) Roll back a transaction in databases that support transactions.
private static void	throwMalformedColumnNameException(java.lang.String criteriaPhrase, java.lang.String columnName) Throws a TorqueException with the malformed column name error message.

Methods inherited from class java.lang.Object

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

Field Detail

ORDER_BY

public static final java.lang.String ORDER_BY

Constant criteria key to reference ORDER BY columns.

IGNORE_CASE

public static final java.lang.String IGNORE_CASE

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

TABLE_NAME

public static final java.lang.String TABLE_NAME

Classes that implement this class should override this value.

DEFAULT_MAP_BUILDER

public static final java.lang.String DEFAULT_MAP_BUILDER

The Turbine default MapBuilder.

mapBuilders

private static java.util.Hashtable mapBuilders

Hashtable that contains the cached mapBuilders.

category

protected static org.apache.log4j.Category category

Constructor Detail

BasePeer

public BasePeer()

Method Detail

hashtableToByteArray

public static byte[] hashtableToByteArray(java.util.Hashtable hash)
                                   throws TorqueException

Converts a hashtable to a byte array for storage/serialization.

Parameters:

hash - The Hashtable to convert.

Returns:

A byte[] with the converted Hashtable.

Throws:

TorqueException -

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 Turbineresources 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. Primary use is with TurbineUserPeer.

Parameters:

tableName - Name of table.

columnNames - A String[].

Returns:

A String[].

beginTransaction

public static DBConnection beginTransaction(java.lang.String dbName)
                                     throws TorqueException

Begin a transaction. This method will fallback gracefully to return a normal connection, if the database being accessed does not support transactions.

Parameters:

dbName - Name of database.

Returns:

The DBConnection for the transaction.

Throws:

TorqueException -

commitTransaction

public static void commitTransaction(DBConnection dbCon)
                              throws TorqueException

Commit a transaction. This method takes care of releasing the connection after the commit. in databases that do not support transactions, it only returns the connection.

Parameters:

dbCon - The DBConnection for the transaction.

Throws:

TorqueException -

rollBackTransaction

public static void rollBackTransaction(DBConnection dbCon)
                                throws TorqueException

Roll back a transaction in databases that support transactions. It also releases the connection. in databases that do not support transactions, this method will log the attempt and release the connection.

Parameters:

dbCon - The DBConnection for the transaction.

Throws:

TorqueException -

deleteAll

public static void deleteAll(DBConnection dbCon,
                             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:

dbCon - A DBConnection.

table - The table to delete records from.

column - The column in the where clause.

value - The value of the column.

Throws:

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 -

doDelete

public static void doDelete(Criteria criteria)
                     throws TorqueException

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

Parameters:

criteria - The criteria to use.

Throws:

TorqueException -

doDelete

public static void doDelete(Criteria criteria,
                            DBConnection dbCon)
                     throws TorqueException

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

Parameters:

criteria - The criteria to use.

dbCon - A DBConnection.

Throws:

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 -

doInsert

public static ObjectKey doInsert(Criteria criteria,
                                 DBConnection dbCon)
                          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.

dbCon - A DBConnection.

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 -

insertOrUpdateRecord

private static void insertOrUpdateRecord(com.workingdogs.village.Record rec,
                                         java.lang.String tableName,
                                         Criteria criteria)
                                  throws TorqueException

Grouping of code used in both doInsert() and doUpdate() methods. Sets up a Record for saving.

Parameters:

rec - A Record.

tableName - Name of table.

criteria - A Criteria.

Throws:

TorqueException -

createQueryString

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

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

Parameters:

criteria - A Criteria.

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 -

doSelect

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

Returns all results.

Parameters:

criteria - A Criteria.

dbCon - A DBConnection.

Returns:

List of Record objects.

Throws:

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 -

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 -

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 -

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          boolean singleRecord,
                                          DBConnection dbCon)
                                   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.

dbCon - A DBConnection.

Returns:

List of Record objects.

Throws:

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 -

executeQuery

public static java.util.List executeQuery(java.lang.String queryString,
                                          int start,
                                          int numberOfResults,
                                          boolean singleRecord,
                                          DBConnection dbCon)
                                   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.

dbCon - A DBConnection.

Returns:

List of Record objects.

Throws:

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.db.LargeSelect.

Parameters:

qds - A QueryDataSet.

Returns:

List of Record objects.

Throws:

TorqueException -

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.db.LargeSelect.

Parameters:

qds - A QueryDataSet.

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

Throws:

TorqueException -

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.db.LargeSelect.

Parameters:

qds - A QueryDataSet.

numberOfResults - The number of results to return.

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

Throws:

TorqueException -

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.db.LargeSelect.

Parameters:

qds - A QueryDataSet.

start - where to start retrieving Records.

numberOfResults - The number of results to return.

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

Throws:

TorqueException -

getPrimaryKey

private static ColumnMap getPrimaryKey(Criteria criteria)
                                throws TorqueException

Helper method which returns the primary key contained in the given Criteria object.

Parameters:

criteria - A Criteria.

Returns:

ColumnMap if the Criteria object contains a primary key, or null if it doesn't.

Throws:

TorqueException -

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 -

doUpdate

public static void doUpdate(Criteria updateValues,
                            DBConnection dbCon)
                     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.

dbCon - A DBConnection.

Throws:

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 -

doUpdate

public static void doUpdate(Criteria selectCriteria,
                            Criteria updateValues,
                            DBConnection dbCon)
                     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.

dbCon - A DBConnection.

Throws:

TorqueException -

executeStatement

public static int executeStatement(java.lang.String stmt)
                            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:

stmt - A String with the sql statement to execute.

Returns:

The number of rows affected.

Throws:

TorqueException -

executeStatement

public static int executeStatement(java.lang.String stmt,
                                   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:

stmt - A String with the sql statement to execute.

dbName - Name of database to connect to.

Returns:

The number of rows affected.

Throws:

TorqueException, - a generic exception.

executeStatement

public static int executeStatement(java.lang.String stmt,
                                   DBConnection dbCon)
                            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:

stmt - A String with the sql statement to execute.

dbCon - A DBConnection.

Returns:

The number of rows affected.

Throws:

TorqueException -

handleMultipleRecords

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

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:

TorqueException - Couldn't handle multiple records.

handleMultiple

protected static void handleMultiple(com.workingdogs.village.DataSet ds)
                              throws TorqueException

Deprecated. Use the better-named handleMultipleRecords() instead.

getMapBuilder

public static MapBuilder getMapBuilder()
                                throws TorqueException

This method returns the MapBuilder specified in the TurbineResources.properties file. By default, this is org.apache.torque.util.db.map.TurbineMapBuilder.

Returns:

A MapBuilder.

getMapBuilder

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

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 this class for speed.

Returns:

A MapBuilder, or null (and logs the error) if the MapBuilder was not found.

doPSSelect

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

Performs a SQL select using a PreparedStatement.

Throws:

TorqueException - Error performing database query.

doPSSelect

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

Do a Prepared Statement select according to the given criteria

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.

throwMalformedColumnNameException

private static void throwMalformedColumnNameException(java.lang.String criteriaPhrase,
                                                      java.lang.String columnName)
                                               throws TorqueException

Throws a TorqueException with the malformed column name error message. The error message looks like this:

Malformed column name in Criteria [criteriaPhrase]: '[columnName]' is not of the form 'table.column'

Parameters:

criteriaPhrase - a String, one of "select", "join", or "order by"

columnName - a String containing the offending column name