org.apache.torque.util
Class BasePeer

java.lang.Object
  extended byorg.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.55.2.2 2003/06/20 08:40:02 mpoeschl Exp $
Author:
Frank Y. Kim, John D. McNally, Brett McLaughlin, Stephen Haberman
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 void createPreparedStatement(Criteria criteria, java.lang.StringBuffer queryString, java.util.List params)
          Create a new PreparedStatement.
(package private) static Query createQuery(Criteria criteria)
          Method to create an SQL query based on values in a Criteria.
(package private) static java.lang.String createQueryDisplayString(Criteria criteria)
          Method to create an SQL query for display only based on values in a Criteria.
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)
          Method to perform deletes based on values and keys in a Criteria.
static void doDelete(Criteria criteria, 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 selectCriteria, 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 stmt)
          Utility method which executes a given sql statement.
static int executeStatement(java.lang.String stmt, java.sql.Connection con)
          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.
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, 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

DEFAULT_MAP_BUILDER

public static final java.lang.String DEFAULT_MAP_BUILDER
The Turbine default MapBuilder.

See Also:
Constant Field Values

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[].

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

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,
                            java.sql.Connection con)
                     throws TorqueException
Method to perform deletes based on values and keys in a Criteria.

Parameters:
criteria - The criteria to use.
con - A Connection.
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,
                                 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

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

createQueryDisplayString

static java.lang.String createQueryDisplayString(Criteria criteria)
                                          throws TorqueException
Method to create an SQL query for display only based on values in a Criteria.

Parameters:
criteria - A Criteria.
Throws:
TorqueException - Trouble creating the query string.

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.
Throws:
TorqueException - Trouble creating the query string.

createQuery

static Query createQuery(Criteria criteria)
                  throws TorqueException
Method to create an SQL query based on values in a Criteria. Note that final manipulation of the limit and offset are performed when the query is actually executed.

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,
                                      java.sql.Connection con)
                               throws TorqueException
Returns all results.

Parameters:
criteria - A Criteria.
con - A Connection.
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,
                                          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

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,
                                          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

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.

Throws:
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.

Throws:
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.

Throws:
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.

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,
                            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

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,
                            java.sql.Connection con)
                     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.
con - A Connection.
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,
                                   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:
stmt - A String with the sql statement to execute.
con - A Connection.
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.

Throws:
TorqueException

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.
Throws:
TorqueException

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,
                                        java.sql.Connection con)
                                 throws TorqueException
Performs a SQL select using a PreparedStatement. Note: this method does not handle null criteria values.

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

Throws:
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.

Throws:
TorqueException

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
Throws:
TorqueException


Copyright © 1999-2003 Apache Software Foundation. All Rights Reserved.