org.apache.turbine.om.peer
Class BasePeer

java.lang.Object
  |
  +--org.apache.turbine.om.peer.BasePeer
Direct Known Subclasses:
GroupPeer, JobEntryPeer, PermissionPeer, RolePeer, RolePermissionPeer, TurbineUserPeer, UserGroupRolePeer

public abstract class BasePeer
extends java.lang.Object

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$
Author:
Frank Y. Kim, John D. McNally, Brett McLaughlin

Field Summary
static java.lang.String DEFAULT_MAP_BUILDER
          The Turbine default MapBuilder.
static java.lang.String IGNORE_CASE
           
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.Vector doPSSelect(Criteria criteria)
          Do a Prepared Statement select according to the given criteria
static java.util.Vector doPSSelect(Criteria criteria, DBConnection dbCon)
          Performs a SQL select using a PreparedStatement.
static java.util.Vector doSelect(Criteria criteria)
          Old method for performing a SELECT.
static java.util.Vector doSelect(Criteria criteria, DBConnection dbCon)
          Old method for performing a SELECT.
static void doUpdate(Criteria updateValues)
          Use this method for performing an update of the kind:
static void doUpdate(Criteria selectCriteria, Criteria updateValues)
          Use this method for performing an update of the kind:
static void doUpdate(Criteria selectCriteria, Criteria updateValues, DBConnection dbCon)
          Use this method for performing an update of the kind:
static void doUpdate(Criteria updateValues, DBConnection dbCon)
          Use this method for performing an update of the kind:
static java.util.Vector executeQuery(java.lang.String queryString)
          Utility method which executes a given sql statement.
static java.util.Vector executeQuery(java.lang.String queryString, boolean singleRecord, DBConnection dbCon)
          Method for performing a SELECT.
static java.util.Vector executeQuery(java.lang.String queryString, int start, int numberOfResults, boolean singleRecord, DBConnection dbCon)
          Method for performing a SELECT.
static java.util.Vector executeQuery(java.lang.String queryString, int start, int numberOfResults, java.lang.String dbName, boolean singleRecord)
          Method for performing a SELECT.
static java.util.Vector executeQuery(java.lang.String queryString, java.lang.String dbName)
          Utility method which executes a given sql statement.
static java.util.Vector 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.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds)
          Returns all records in a QueryDataSet as a Vector of Record objects.
static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds, boolean singleRecord)
          Returns all records in a QueryDataSet as a Vector of Record objects.
static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds, int numberOfResults, boolean singleRecord)
          Returns numberOfResults records in a QueryDataSet as a Vector of Record objects.
static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds, int start, int numberOfResults, boolean singleRecord)
          Returns numberOfResults records in a QueryDataSet as a Vector 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.
 
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

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.
Constructor Detail

BasePeer

public BasePeer()
Method Detail

hashtableToByteArray

public static byte[] hashtableToByteArray(java.util.Hashtable hash)
                                   throws java.lang.Exception
Converts a hashtable to a byte array for storage/serialization.
Parameters:
hash - The Hashtable to convert.
Returns:
A byte[] with the converted Hashtable.
Throws:
Exception, - a generic exception.

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 java.lang.Exception
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:
Exception, - a generic exception.

commitTransaction

public static void commitTransaction(DBConnection dbCon)
                              throws java.lang.Exception
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:
Exception, - a generic exception.

rollBackTransaction

public static void rollBackTransaction(DBConnection dbCon)
                                throws java.lang.Exception
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:
Exception, - a generic exception.

deleteAll

public static void deleteAll(DBConnection dbCon,
                             java.lang.String table,
                             java.lang.String column,
                             int value)
                      throws java.lang.Exception
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:
Exception, - a generic exception.

deleteAll

public static void deleteAll(java.lang.String table,
                             java.lang.String column,
                             int value)
                      throws java.lang.Exception
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:
Exception, - a generic exception.

doDelete

public static void doDelete(Criteria criteria)
                     throws java.lang.Exception
Method to perform deletes based on values and keys in a Criteria.
Parameters:
criteria - The criteria to use.
Throws:
Exception, - a generic exception.

doDelete

public static void doDelete(Criteria criteria,
                            DBConnection dbCon)
                     throws java.lang.Exception
Method to perform deletes based on values and keys in a Criteria.
Parameters:
criteria - The criteria to use.
dbCon - A DBConnection.
Throws:
Exception, - a generic exception.

doInsert

public static ObjectKey doInsert(Criteria criteria)
                          throws java.lang.Exception
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:
Exception, - a generic exception.

doInsert

public static ObjectKey doInsert(Criteria criteria,
                                 DBConnection dbCon)
                          throws java.lang.Exception
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:
Exception, - a generic exception.

insertOrUpdateRecord

private static void insertOrUpdateRecord(com.workingdogs.village.Record rec,
                                         java.lang.String tableName,
                                         Criteria criteria)
                                  throws java.lang.Exception
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:
Exception, - a generic exception.

createQueryString

public static java.lang.String createQueryString(Criteria criteria)
                                          throws java.lang.Exception
Method to create an SQL query based on values in a Criteria.
Parameters:
criteria - A Criteria.
Throws:
java.lang.Exception - Trouble creating the query string.

doSelect

public static java.util.Vector doSelect(Criteria criteria)
                                 throws java.lang.Exception
Old method for performing a SELECT. Returns all results.
Parameters:
criteria - A Criteria.
Returns:
Vector of Record objects.
Throws:
Exception, - a generic exception.

doSelect

public static java.util.Vector doSelect(Criteria criteria,
                                        DBConnection dbCon)
                                 throws java.lang.Exception
Old method for performing a SELECT. Returns all results.
Parameters:
criteria - A Criteria.
dbCon - A DBConnection.
Returns:
Vector of Record objects.
Throws:
Exception, - a generic exception.

executeQuery

public static java.util.Vector executeQuery(java.lang.String queryString)
                                     throws java.lang.Exception
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:
Vector of Record objects.
Throws:
Exception, - a generic exception.

executeQuery

public static java.util.Vector executeQuery(java.lang.String queryString,
                                            java.lang.String dbName)
                                     throws java.lang.Exception
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:
Vector of Record objects.
Throws:
Exception, - a generic exception.

executeQuery

public static java.util.Vector executeQuery(java.lang.String queryString,
                                            java.lang.String dbName,
                                            boolean singleRecord)
                                     throws java.lang.Exception
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:
Vector of Record objects.
Throws:
Exception, - a generic exception.

executeQuery

public static java.util.Vector executeQuery(java.lang.String queryString,
                                            boolean singleRecord,
                                            DBConnection dbCon)
                                     throws java.lang.Exception
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.
dbCon - A DBConnection.
Returns:
Vector of Record objects.
Throws:
Exception, - a generic exception.

executeQuery

public static java.util.Vector executeQuery(java.lang.String queryString,
                                            int start,
                                            int numberOfResults,
                                            java.lang.String dbName,
                                            boolean singleRecord)
                                     throws java.lang.Exception
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:
Vector of Record objects.
Throws:
Exception, - a generic exception.

executeQuery

public static java.util.Vector executeQuery(java.lang.String queryString,
                                            int start,
                                            int numberOfResults,
                                            boolean singleRecord,
                                            DBConnection dbCon)
                                     throws java.lang.Exception
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.
dbName - The database to connect to.
singleRecord - Whether or not we want to select only a single record.
dbCon - A DBConnection.
Returns:
Vector of Record objects.
Throws:
Exception, - a generic exception.

getSelectResults

public static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds)
                                         throws java.lang.Exception
Returns all records in a QueryDataSet as a Vector of Record objects. Used for functionality like util.db.LargeSelect.
Parameters:
qds - A QueryDataSet.
Returns:
Vector of Record objects.
Throws:
Exception, - a generic exception.

getSelectResults

public static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds,
                                                boolean singleRecord)
                                         throws java.lang.Exception
Returns all records in a QueryDataSet as a Vector 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:
Exception, - a generic exception.

getSelectResults

public static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds,
                                                int numberOfResults,
                                                boolean singleRecord)
                                         throws java.lang.Exception
Returns numberOfResults records in a QueryDataSet as a Vector 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:
Exception, - a generic exception.

getSelectResults

public static java.util.Vector getSelectResults(com.workingdogs.village.QueryDataSet qds,
                                                int start,
                                                int numberOfResults,
                                                boolean singleRecord)
                                         throws java.lang.Exception
Returns numberOfResults records in a QueryDataSet as a Vector 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:
Exception, - a generic exception.

getPrimaryKey

private static ColumnMap getPrimaryKey(Criteria criteria)
                                throws java.lang.Exception
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:
Exception, - a generic exception.

doUpdate

public static void doUpdate(Criteria updateValues)
                     throws java.lang.Exception
Use this method for performing an update of the kind:

"WHERE primary_key_id = an int"

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.

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:
Exception, - a generic exception.

doUpdate

public static void doUpdate(Criteria updateValues,
                            DBConnection dbCon)
                     throws java.lang.Exception
Use this method for performing an update of the kind:

"WHERE primary_key_id = an int"

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.

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:
Exception, - a generic exception.

doUpdate

public static void doUpdate(Criteria selectCriteria,
                            Criteria updateValues)
                     throws java.lang.Exception
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...

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

Parameters:
selectCriteria - A Criteria object containing values used in where clause.
updateValues - A Criteria object containing values used in set clause.
Throws:
Exception, - a generic exception.

doUpdate

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

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

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:
Exception, - a generic exception.

executeStatement

public static int executeStatement(java.lang.String stmt)
                            throws java.lang.Exception
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:
Exception, - a generic exception.

executeStatement

public static int executeStatement(java.lang.String stmt,
                                   java.lang.String dbName)
                            throws java.lang.Exception
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:
Exception, - a generic exception.

executeStatement

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

handleMultipleRecords

protected static void handleMultipleRecords(com.workingdogs.village.DataSet ds)
                                     throws java.lang.Exception
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:
java.lang.Exception - Couldn't handle multiple records.

handleMultiple

protected static void handleMultiple(com.workingdogs.village.DataSet ds)
                              throws java.lang.Exception
Deprecated. Use the better-named handleMultipleRecords() instead.


getMapBuilder

public static MapBuilder getMapBuilder()
This method returns the MapBuilder specified in the TurbineResources.properties file. By default, this is org.apache.turbine.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.turbine.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.Vector doPSSelect(Criteria criteria,
                                          DBConnection dbCon)
                                   throws java.lang.Exception
Performs a SQL select using a PreparedStatement.
Throws:
java.lang.Exception - Error performing database query.

doPSSelect

public static java.util.Vector 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 java.lang.Exception
Create a new PreparedStatement. It builds a string representation of a query and a list of PreparedStatement parameters.


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