com.is.jrf
Class AbstractDomain

java.lang.Object
  |
  +--com.is.jrf.AbstractDomain

All Implemented Interfaces:

JRFConstants

Direct Known Subclasses:

AbstractStaticDomain

public abstract class AbstractDomain

extends java.lang.Object

implements JRFConstants

Subclasses of AbstractDomain are generally table-specific objects.

If you have questions, make sure you read the documentation. (see Package.html).

Note: The "current date/time" function will be inserted into the update SQL whenever a JRFConstants.CURRENT_TIMESTAMP is encountered for an attribute.

Note: For an example of how to use the executeSQLQuery() method, see the implementation of the findCustom(sqlString,jdbcHelper) method.

Note: If any of the superclass methods should never be used, you can override them with a method that throws an exception.

JDBCHelperPool is now supported (version 1.5). Find methods handle the pools differently than the Update (save,delete) methods. The find methods "manually" return the JDBCHelper to the pool (if the JDBCHelper is not part of a transaction). The update methods depend upon the endTransaction and rollback methods to return the connection to the pool.

Inner Class Summary

protected static interface

AbstractDomain.RowHandler

Fields inherited from interface com.is.jrf.JRFConstants

CURRENT_DATE, CURRENT_TIMESTAMP, DEFAULT_TO_EMPTY_STRING, DEFAULT_TO_FALSE, DEFAULT_TO_NOW, DEFAULT_TO_NULL, DEFAULT_TO_ONE, DEFAULT_TO_TODAY, DEFAULT_TO_TRUE, DEFAULT_TO_ZERO, EQUALS, NATURAL_PRIMARY_KEY, NO_POST_FIND, NOT_EQUALS, OPTIMISTIC_LOCK, REQUIRED, SEQUENCED_PRIMARY_KEY, SUBTYPE_IDENTIFIER, UNIQUE

Constructor Summary

AbstractDomain()
This constructor must be executed whether implicitly or explicitly.

AbstractDomain(int option)
The option argument affects the behavior of this framework.

Method Summary

void	addColumnSpec(ColumnSpec aColumnSpec)
void	addJoinTable(JoinTable aJoinTable)
void	addSubtypeColumnSpec(AbstractColumnSpec aColumnSpec) Cannot add CompoundPrimaryKeyColumnSpec using this
static void	addSubtypeDomain(java.lang.Object subtypeIdentifierValue, java.lang.Class domainClass) Inform this supertype domain class of a subtype domain class
void	beginTransaction() This is a pass-through method that adds the default JDBCHelper to the argument list.
void	beginTransaction(JDBCHelper aJDBCHelper) This is a helper method that goes with the endTransaction() method.
protected PersistentObject	convertToPersistentObject(JDBCHelper aJDBCHelper) The reflection in Java 2 makes this method almost as efficient as hard-coding the gets and sets in a subclass.
PersistentObject	convertToSubtypePersistentObject(PersistentObject aPO1) Copy the attribute values from a supertype instance to a subtype instance.
void	copyAttributes(PersistentObject aPO1, PersistentObject aPO2) Copy the ColumnSpec attributes from one PersistentObject to another. Note: If this is a subtype Domain instance then the subtype fields will be copied as well.
void	createTable()
void	createTable(JDBCHelper aJDBCHelper) Build and execute SQL to create a table with default column types for this domain.
PersistentObject	decodePrimaryKey(java.lang.String aString) Encode the primary key for the given PersistentObject instance as a string that can be decoded later.
int	delete(PersistentObject aPO) This is a pass-through method that adds the default JDBCHelper to the argument list.
int	delete(PersistentObject aPO, JDBCHelper aJDBCHelper) Delete one row from the database.
java.lang.String	delimitString(java.lang.String aString) This is a helper method for use by subclasses that are creating SQL.
void	dropTable(boolean ignoreErrors) Execute SQL to drop the table for this domain object - use the default JDBCHelper.
void	dropTable(boolean ignoreErrors, JDBCHelper aJDBCHelper) Execute SQL to drop the table for this domain object.
java.lang.String	encodePrimaryKey(PersistentObject aPO) Encode the primary key for the given PersistentObject instance as a string that can be decoded later.
void	endTransaction() This method commits the transaction and closes the JDBCHelper.
void	endTransaction(JDBCHelper aJDBCHelper) This method commits the transaction and closes the JDBCHelper.
protected void	executeSQLQuery(java.lang.String sql, AbstractDomain.RowHandler aRowHandler) Execute the SQL and pass each row to the given RowHandler.
protected void	executeSQLQuery(java.lang.String sql, AbstractDomain.RowHandler aRowHandler, JDBCHelper aJDBCHelper) Execute the SQL and pass each row to the given RowHandler.
protected int	executeSQLUpdate(java.lang.String sql) This is a pass-through method that adds the default JDBCHelper to the argument list.
protected int	executeSQLUpdate(java.lang.String sql, JDBCHelper aJDBCHelper) Execute SQL that updates, deletes, or inserts.
protected PersistentObject	finalFind(java.lang.Object pkOrPersistentObject, JDBCHelper aJDBCHelper) This is a protected method that cannot be overridden.
PersistentObject	find(java.lang.Object pkOrPersistentObject) This is a pass-through method that adds the default JDBCHelper to the argument list.
PersistentObject	find(java.lang.Object pkOrPersistentObject, JDBCHelper aJDBCHelper) Find and return one PersistentObject using either the raw primary key or the primary key attribute(s) from a PersistentObject object.
java.util.List	find(SelectSQLBuilder builder)
java.util.List	find(SelectSQLBuilder builder, JDBCHelper aJDBCHelper)
java.util.List	findAll() This is a pass-through method that adds the default JDBCHelper to the argument list.
java.util.List	findAll(JDBCHelper aJDBCHelper) Find all PersistentObject values found in my table.
java.sql.Timestamp	findCurrentTimestamp() Execute SQL that will return the current date and time from the database.
java.sql.Timestamp	findCurrentTimestamp(JDBCHelper aJDBCHelper) Execute SQL that will find the current timestamp value from the database.
java.util.List	findCustom(java.lang.String sql) This is a pass-through method that adds the default JDBCHelper to the argument list.
java.util.List	findCustom(java.lang.String sql, JDBCHelper aJDBCHelper) This method should *rarely*, if ever, be used by subclasses.
protected java.lang.Integer	findInteger(java.lang.String sql) This is a pass-through method that adds the default JDBCHelper to the parameter list.
protected java.lang.Integer	findInteger(java.lang.String sql, JDBCHelper aJDBCHelper) This method calls findLong and casts the result down to an Integer.
protected java.lang.Long	findLong(java.lang.String sql) This is a pass-through method that adds the default JDBCHelper to the parameter list.
protected java.lang.Long	findLong(java.lang.String sql, JDBCHelper aJDBCHelper) Execute SQL that returns a Long.
java.util.List	findOrderBy(java.lang.String orderByString) This method adds an ORDER BY clause to the basic findAll SQL.
java.util.List	findOrderBy(java.lang.String orderByString, JDBCHelper aJDBCHelper) This method adds an ORDER BY clause to the basic findAll SQL.
java.util.List	findWhere(java.lang.String whereString) This method adds a where clause to the basic findAll SQL.
java.util.List	findWhere(java.lang.String whereString, JDBCHelper aJDBCHelper) This method adds a where clause to the basic findAll SQL.
java.util.List	findWhereOrderBy(java.lang.String whereString, java.lang.String orderByString) This method adds both a WHERE and an ORDER BY clause to the basic findAll SQL.
java.util.List	findWhereOrderBy(java.lang.String whereString, java.lang.String orderByString, JDBCHelper aJDBCHelper) This method adds both a WHERE and an ORDER BY clause to the basic findAll SQL.
java.util.List	getAllColumnSpecs()
java.util.List	getColumnSpecs()
CreateTableSQLBuilder	getCreateTableSQLBuilder()
DatabasePolicy	getDatabasePolicy()
int	getEndingIndex() Return the index of the last row to be converted to an object and returned.
InsertSQLBuilder	getInsertSQLBuilder()
protected JDBCHelper	getJDBCHelper() Return a JDBCHelper instance from the pool or return the default instance.
JDBCHelperPool	getJDBCHelperPool()
java.util.List	getJoinTables()
ColumnSpec	getPrimaryKeyColumnSpec()
boolean	getReturnSavedObject() If true, the object is retrieved from the database and is returned to the user at the end of the save operation.
SelectSQLBuilder	getSelectSQLBuilder()
boolean	getShouldAutoCommit() The default is false.
int	getStartingIndex() Return the index of the first row to be converted to an object and returned.
java.util.List	getSubtypeColumnSpecs()
JoinTable	getSubtypeTable()
java.lang.String	getSubtypeTableName()
java.lang.String	getTableAlias()
java.lang.String	getTableName()
UpdateSQLBuilder	getUpdateSQLBuilder()
boolean	getValidateBeforeSaving() If false, no validation will be done on this object before saving it.
abstract PersistentObject	newPersistentObject() Subclasses must implement this to create a new PersistentObject.
protected java.lang.Long	nextSequence(JDBCHelper aJDBCHelper) Use JDBC to call a stored procedure to get a the next available sequence id.
protected void	postDelete(PersistentObject aPO, JDBCHelper aJDBCHelper) This is the default, no-operation implementation.
protected void	postFind(PersistentObject aPO, JDBCHelper aJDBCHelper) This is the default, no-operation implementation which is executed for all found objects.
protected void	postSave(PersistentObject aPO, JDBCHelper aJDBCHelper) This is the default, no-operation implementation.
protected void	preDelete(PersistentObject aPO, JDBCHelper aJDBCHelper) This is the default, no-operation implementation.
protected void	preSave(PersistentObject aPO, JDBCHelper aJDBCHelper) This is the default, no-operation implementation.
protected void	preValidate(PersistentObject aPO, JDBCHelper aJDBCHelper) This is the default, no-operation implementation.
void	quietlyRollbackAndClose(JDBCHelper aJDBCHelper) If the rollback doesn't work, we don't need to know about it.
void	resetStartingAndEndingIndexes() Reset the starting and ending indexes so the whole resultset will be returned the next time a query is called.
PersistentObject	save(PersistentObject aPO) This is a pass-through method that adds the default JDBCHelper to the argument list.
PersistentObject	save(PersistentObject aPO, JDBCHelper aJDBCHelper) Save the PersistentObject to the database after validating the object with this.validate(aPO,aJDBCHelper).
void	setDatabasePolicy(DatabasePolicy dbPolicy)
void	setEndingIndex(int v) Set the index of the last row to be converted to an object and returned.
void	setJDBCHelper(JDBCHelper aJDBCHelper) Set the default JDBCHelper instance.
void	setJDBCHelperPool(JDBCHelperPool aJDBCHelperPool)
void	setJDBCHelperPoolName(java.lang.String poolName)
void	setReturnSavedObject(boolean b)
void	setShouldAutoCommit(boolean b)
void	setStartingIndex(int v) Set the index of the first row to be converted to an object and returned.
void	setSubtypeTableName(java.lang.String s) If the name looks like this: 'Customer c', then 'Customer' will be the tableName and 'c' will be the tableAlias.
void	setTableAlias(java.lang.String alias)
void	setTableName(java.lang.String s) If the name looks like this: 'Customer c', then 'Customer' will be the tableName and 'c' will be the tableAlias.
protected abstract void	setup() This method is called by the constructors.
void	setUseANSIJoins(boolean b)
void	setUsePostFind(boolean b)
void	setValidateBeforeSaving(boolean b)
boolean	useANSIJoins() If true, ANSI JOIN clauses will be used
boolean	usePostFind() If true, the postFind() method will be called.
void	validate(PersistentObject aPO) This is a pass-through method that adds the default JDBCHelper to the argument list.
void	validate(PersistentObject aPO, JDBCHelper aJDBCHelper) This method validates a PersistentObject using the ColumnSpec objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractDomain

public AbstractDomain(int option)

The option argument affects the behavior of this framework. This was added for the NO_POST_FIND option, but others may be added.

Parameters:

option - a value of type 'int'

AbstractDomain

public AbstractDomain()

This constructor must be executed whether implicitly or explicitly. If the subclass setup() method does not set the database policy, table name or JDBCHelper properly, then a NullPointerException is thrown with a helpful error message rather than having it happen deep in the stack where it is hard to figure out what went wrong.

Method Detail

addSubtypeDomain

public static void addSubtypeDomain(java.lang.Object subtypeIdentifierValue,
                                    java.lang.Class domainClass)

Inform this supertype domain class of a subtype domain class

Parameters:

subtypeIdentifierValue - - value of the SUBTYPE_IDENTIFIER field

domainClass - - value of the SUBTYPE_IDENTIFIER field

getValidateBeforeSaving

public boolean getValidateBeforeSaving()

If false, no validation will be done on this object before saving it. Validating a UNIQUE attribute requires doing an SQL call so this might improve performance in some cases.

See Also:

setValidateBeforeSaving(boolean)

setValidateBeforeSaving

public void setValidateBeforeSaving(boolean b)

See Also:

getValidateBeforeSaving()

getReturnSavedObject

public boolean getReturnSavedObject()

If true, the object is retrieved from the database and is returned to the user at the end of the save operation. This is important to be true when using an optimisitic lock, a sequenced primary key, or a current timestamp and you intend to make more updates to the object.

Returns:

a value of type 'boolean'

See Also:

setReturnSavedObject(boolean)

setReturnSavedObject

public void setReturnSavedObject(boolean b)

See Also:

getReturnSavedObject()

useANSIJoins

public boolean useANSIJoins()

If true, ANSI JOIN clauses will be used

See Also:

setUseANSIJoins(boolean)

setUseANSIJoins

public void setUseANSIJoins(boolean b)

See Also:

useANSIJoins()

usePostFind

public boolean usePostFind()

If true, the postFind() method will be called.

Returns:

a value of type 'boolean'

See Also:

setUsePostFind(boolean)

setUsePostFind

public void setUsePostFind(boolean b)

See Also:

usePostFind()

getShouldAutoCommit

public boolean getShouldAutoCommit()

The default is false. This value is sent to the JDBCHelper whenever it is set.

setShouldAutoCommit

public void setShouldAutoCommit(boolean b)

getTableName

public java.lang.String getTableName()

setTableName

public void setTableName(java.lang.String s)

If the name looks like this: 'Customer c', then 'Customer' will be the tableName and 'c' will be the tableAlias.

Parameters:

s - a value of type 'String'

getSubtypeTableName

public java.lang.String getSubtypeTableName()

setSubtypeTableName

public void setSubtypeTableName(java.lang.String s)

If the name looks like this: 'Customer c', then 'Customer' will be the tableName and 'c' will be the tableAlias.

Parameters:

s - a value of type 'String'

getSubtypeTable

public JoinTable getSubtypeTable()

setTableAlias

public void setTableAlias(java.lang.String alias)

getTableAlias

public java.lang.String getTableAlias()

getDatabasePolicy

public DatabasePolicy getDatabasePolicy()

setDatabasePolicy

public void setDatabasePolicy(DatabasePolicy dbPolicy)

getJDBCHelper

protected JDBCHelper getJDBCHelper()

Return a JDBCHelper instance from the pool or return the default instance.

Returns:

a value of type 'JDBCHelper'

setJDBCHelper

public void setJDBCHelper(JDBCHelper aJDBCHelper)

Set the default JDBCHelper instance.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

getJDBCHelperPool

public JDBCHelperPool getJDBCHelperPool()

setJDBCHelperPool

public void setJDBCHelperPool(JDBCHelperPool aJDBCHelperPool)

Parameters:

aJDBCHelperPool - a value of type 'JDBCHelperPool'

setJDBCHelperPoolName

public void setJDBCHelperPoolName(java.lang.String poolName)

Parameters:

aJDBCHelperPool - a value of type 'JDBCHelperPool'

addColumnSpec

public void addColumnSpec(ColumnSpec aColumnSpec)

getColumnSpecs

public java.util.List getColumnSpecs()

addSubtypeColumnSpec

public void addSubtypeColumnSpec(AbstractColumnSpec aColumnSpec)

Cannot add CompoundPrimaryKeyColumnSpec using this

getSubtypeColumnSpecs

public java.util.List getSubtypeColumnSpecs()

getAllColumnSpecs

public java.util.List getAllColumnSpecs()

Returns:

the union of the regular and the subtype columnspec lists

addJoinTable

public void addJoinTable(JoinTable aJoinTable)

getJoinTables

public java.util.List getJoinTables()

getPrimaryKeyColumnSpec

public ColumnSpec getPrimaryKeyColumnSpec()

getStartingIndex

public int getStartingIndex()

Return the index of the first row to be converted to an object and returned. The index numbers start at 1 (not 0).

Returns:

a value of type 'int'

setStartingIndex

public void setStartingIndex(int v)

Set the index of the first row to be converted to an object and returned. The index numbers start at 1 (not 0). Don't forget to reset these before reusing this domain instance.

See Also:

resetStartingAndEndingIndexes()

getEndingIndex

public int getEndingIndex()

Return the index of the last row to be converted to an object and returned. The index numbers start at 1 (not 0).

Returns:

a value of type 'int'

setEndingIndex

public void setEndingIndex(int v)

Set the index of the last row to be converted to an object and returned. The index numbers start at 1 (not 0). Don't forget to reset these before reusing this domain instance.

See Also:

resetStartingAndEndingIndexes()

resetStartingAndEndingIndexes

public void resetStartingAndEndingIndexes()

Reset the starting and ending indexes so the whole resultset will be returned the next time a query is called.

setup

protected abstract void setup()

This method is called by the constructors. Example implementation: // this.setTableName("Customer"); // this.setJDBCHelper(JDBCHelperFactory.create()); // this.setDatabasePolicy(new OracleDatabasePolicy()); // this.validateBeforeSaving(true); // true is the default // this.returnSavedObject(true); // true is the default // // this.addColumnSpec( // new IntegerColumnSpec( // "PersonId", // "getPersonId", // "setPersonId", // DEFAULT_TO_NULL, // SEQUENCED_PRIMARY_KEY)); // this.addColumnSpec( // new StringColumnSpec( // "Name", // "getName", // "setName", // DEFAULT_TO_EMPTY_STRING, // REQUIRED, // UNIQUE)); // // JoinTable joinTable = // new OuterJoinTable( // "Status", // "StatusId", // Person column(s) // "Id"); // Status table column(s) // joinTable.addJoinColumn( // new StringJoinColumn( // "Name", // Column Name // "Status", // Alias in case of column name conflict // "getStatusName", // Getter method name // "setStatusName")); // Setter method name // this.addJoinTable(joinTable); //

newPersistentObject

public abstract PersistentObject newPersistentObject()

Subclasses must implement this to create a new PersistentObject.

Returns:

a value of type 'PersistentObject'

postFind

protected void postFind(PersistentObject aPO,
                        JDBCHelper aJDBCHelper)

This is the default, no-operation implementation which is executed for all found objects. Subclasses should override when they want to do something to a PersistentObject after it is found in the database.

The JDBCHelper is an argument so that we have the flexibility to do our own object manipulation using the current row in the result set.

Note: If you wish to use the JDBCHelper to do another SQL call, you must first clone it to get a new connection.

Parameters:

aPO - a value of type 'PersistentObject'

preValidate

protected void preValidate(PersistentObject aPO,
                           JDBCHelper aJDBCHelper)
                    throws ObjectHasChangedException,
                           MissingAttributeException,
                           DuplicateRowException

This is the default, no-operation implementation. Subclasses should override when they want to do something to a PersistentObject before it is validated. If the subclass wants to do an update in the same transaction context, the given JDBCHelper should be used.

Parameters:

aPO - a value of type 'PersistentObject'

preSave

protected void preSave(PersistentObject aPO,
                       JDBCHelper aJDBCHelper)
                throws ObjectHasChangedException,
                       MissingAttributeException,
                       DuplicateRowException

This is the default, no-operation implementation. Subclasses should override when they want to do something to a PersistentObject before it is saved. If the subclass wants to do an update in the same transaction context, the given JDBCHelper should be used.

Parameters:

aPO - a value of type 'PersistentObject'

postSave

protected void postSave(PersistentObject aPO,
                        JDBCHelper aJDBCHelper)
                 throws ObjectHasChangedException,
                        MissingAttributeException,
                        DuplicateRowException

This is the default, no-operation implementation. Subclasses should override when they want to do something to a PersistentObject after it is updated or inserted -- like save objects that depend on it's primary key. If the subclass wants to do an update in the same transaction context, the given JDBCHelper should be used.

Parameters:

aPO - a value of type 'PersistentObject'

preDelete

protected void preDelete(PersistentObject aPO,
                         JDBCHelper aJDBCHelper)

This is the default, no-operation implementation. Subclasses should override when they want to do something to a PersistentObject before it is deleted -- like delete objects that depend on it.

Parameters:

aPO - a value of type 'PersistentObject'

postDelete

protected void postDelete(PersistentObject aPO,
                          JDBCHelper aJDBCHelper)

This is the default, no-operation implementation. Subclasses should override when they want to do something to a PersistentObject after it is deleted.

Parameters:

aPO - a value of type 'PersistentObject'

convertToPersistentObject

protected PersistentObject convertToPersistentObject(JDBCHelper aJDBCHelper)
                                              throws java.lang.Exception

The reflection in Java 2 makes this method almost as efficient as hard-coding the gets and sets in a subclass. Overriding is not recommended unless efficiency is a demonstrated problem. This is used by the findCustom(sqlString) method to convert a JDBC row to a value object.
Example override implementation:
// StatusPO aPO = new StatusValue(); // aPO.setStatusId(aJDBCHelper.getInteger("StatusId")); // aPO.setName(aJDBCHelper.getString("Name")); // return value;

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'Object'

Throws:

java.lang.Exception - if an error occurs

find

public final PersistentObject find(java.lang.Object pkOrPersistentObject)

This is a pass-through method that adds the default JDBCHelper to the argument list. This method should not be overridden. Override find(aPO,aJDBCHelper) instead.

Parameters:

pkOrPersistentObject - a value of type 'Object'

Returns:

a value of type 'PersistentObject'

find

public PersistentObject find(java.lang.Object pkOrPersistentObject,
                             JDBCHelper aJDBCHelper)

Find and return one PersistentObject using either the raw primary key or the primary key attribute(s) from a PersistentObject object. If a value is not found then null is returned.

This method can be overridden.

Parameters:

pk - a value of type 'Object'. This can be a PersistentObject with it's primary key field(s) filled in or it can be a single primary key value (i.e. a String or an Integer).

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'PersistentObject'

finalFind

protected final PersistentObject finalFind(java.lang.Object pkOrPersistentObject,
                                           JDBCHelper aJDBCHelper)

This is a protected method that cannot be overridden. Using this method will always do a JDBC call.

Parameters:

pk - a value of type 'Object'. This can be a PersistentObject with it's primary key attribute(s) filled in or a singular primary key value (like String or Integer).

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'PersistentObject'

findAll

public java.util.List findAll()

This is a pass-through method that adds the default JDBCHelper to the argument list.

Returns:

a value of type 'List'

findAll

public java.util.List findAll(JDBCHelper aJDBCHelper)

Find all PersistentObject values found in my table.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'List'

findWhere

public final java.util.List findWhere(java.lang.String whereString)

This method adds a where clause to the basic findAll SQL. 'WHERE' should not be included in the argument string.

findWhere

public final java.util.List findWhere(java.lang.String whereString,
                                      JDBCHelper aJDBCHelper)

This method adds a where clause to the basic findAll SQL. 'WHERE' should not be included in the argument string.

findOrderBy

public final java.util.List findOrderBy(java.lang.String orderByString)

This method adds an ORDER BY clause to the basic findAll SQL. 'ORDER BY' should not be included in the argument string.

findOrderBy

public final java.util.List findOrderBy(java.lang.String orderByString,
                                        JDBCHelper aJDBCHelper)

This method adds an ORDER BY clause to the basic findAll SQL. 'ORDER BY' should not be included in the argument string.

findWhereOrderBy

public final java.util.List findWhereOrderBy(java.lang.String whereString,
                                             java.lang.String orderByString)

This method adds both a WHERE and an ORDER BY clause to the basic findAll SQL. Neither 'ORDER BY' nor 'WHERE' should not be included in the argument strings.

findWhereOrderBy

public final java.util.List findWhereOrderBy(java.lang.String whereString,
                                             java.lang.String orderByString,
                                             JDBCHelper aJDBCHelper)

This method adds both a WHERE and an ORDER BY clause to the basic findAll SQL. Neither 'ORDER BY' nor 'WHERE' should not be included in the argument strings.

find

public java.util.List find(SelectSQLBuilder builder)

find

public java.util.List find(SelectSQLBuilder builder,
                           JDBCHelper aJDBCHelper)

getSelectSQLBuilder

public SelectSQLBuilder getSelectSQLBuilder()

getInsertSQLBuilder

public InsertSQLBuilder getInsertSQLBuilder()

getUpdateSQLBuilder

public UpdateSQLBuilder getUpdateSQLBuilder()

getCreateTableSQLBuilder

public CreateTableSQLBuilder getCreateTableSQLBuilder()

findCustom

public java.util.List findCustom(java.lang.String sql)

This is a pass-through method that adds the default JDBCHelper to the argument list.

Parameters:

sql - a value of type 'String'

Returns:

a value of type 'List'

findCustom

public java.util.List findCustom(java.lang.String sql,
                                 JDBCHelper aJDBCHelper)

This method should *rarely*, if ever, be used by subclasses. The findWhere methods are to be preferred over this method. Subclasses can use this method when (for whatever reason) they need to write totally custom SQL but still want the result set converted to persistent objects. This method returns a List of persistent objects using the given SQL string. An inner class is used that tells the executeSQLQuery() method how to handle the result set rows.

Parameters:

sql - a value of type 'String'

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'List'

validate

public final void validate(PersistentObject aPO)
                    throws MissingAttributeException,
                           DuplicateRowException

This is a pass-through method that adds the default JDBCHelper to the argument list. Do not override this method since it is not called by the framework. Override validate(aPO, aJDBCHelper) instead.

Parameters:

aPO - a value of type 'PersistentObject'

Throws:

MissingAttributeException - if an error occurs

DuplicateRowException - if an error occurs

See Also:

validate(PersistentObject, JDBCHelper)

validate

public void validate(PersistentObject aPO,
                     JDBCHelper aJDBCHelper)
              throws MissingAttributeException,
                     DuplicateRowException

This method validates a PersistentObject using the ColumnSpec objects. When a "problem" is found, the JDBCHelper is rolled back and an exception is thrown. Explicit validation is done here (rather than depend on database constraints at time of insert or update) to give a consistent error message across databases.

Parameters:

aPO - a value of type 'PersistentObject'

Throws:

MissingAttributeException - if a required attribute is missing.

DuplicateRowException - if this row is already in the database.

save

public final PersistentObject save(PersistentObject aPO)
                            throws ObjectHasChangedException,
                                   MissingAttributeException,
                                   DuplicateRowException

This is a pass-through method that adds the default JDBCHelper to the argument list. This method should not be overridden.

Parameters:

aPO - a value of type 'PersistentObject'

Returns:

a value of type 'PersistentObject'

Throws:

ObjectHasChangedException - if an error occurs

MissingAttributeException - if an error occurs

DuplicateRowException - if an error occurs

save

public PersistentObject save(PersistentObject aPO,
                             JDBCHelper aJDBCHelper)
                      throws ObjectHasChangedException,
                             MissingAttributeException,
                             DuplicateRowException

Save the PersistentObject to the database after validating the object with this.validate(aPO,aJDBCHelper). Note for subclasses: If you don't want an exception from the validate method to rollback your transaction, specifically call validate() with a different JDBCHelper (a clone works) before calling save().

Parameters:

aPO - a value of type 'PersistentObject' if the primary key attribute is null, then this does a SQL insert.

Returns:

a value of type 'PersistentObject'

Throws:

ObjectHasChangedException - if an error occurs

MissingAttributeException - if an error occurs

DuplicateRowException - if an error occurs

delete

public final int delete(PersistentObject aPO)

This is a pass-through method that adds the default JDBCHelper to the argument list.

Parameters:

aPO - a value of type 'PersistentObject'

Returns:

a value of type 'int'

delete

public int delete(PersistentObject aPO,
                  JDBCHelper aJDBCHelper)

Delete one row from the database. No application exceptions need to be declared here since the integer number of rows deleted is the return value.

Parameters:

aPO - a value of type 'PersistentObject'

Returns:

a value of type 'int' which is the number of rows deleted. This should always be zero or one, but this is not guaranteed if the wrong attribute is defined as the primary key.

createTable

public void createTable()

createTable

public void createTable(JDBCHelper aJDBCHelper)

Build and execute SQL to create a table with default column types for this domain. This was written to create test tables for running the test suite. If this class represents a subtype table, that is the table that will be created.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

dropTable

public void dropTable(boolean ignoreErrors)

Execute SQL to drop the table for this domain object - use the default JDBCHelper.

Parameters:

ignoreErrors - a value of type 'boolean'

dropTable

public void dropTable(boolean ignoreErrors,
                      JDBCHelper aJDBCHelper)

Execute SQL to drop the table for this domain object. If this class represents a subtype table, then the subtype table will be dropped instead. This code is unfortunately ugly because of the reimplementation of error handling when ignoreErrors is true.

Parameters:

ignoreErrors - a value of type 'boolean' - It is often that we don't want to know if the table wasn't there.

aJDBCHelper - a value of type 'JDBCHelper'

executeSQLQuery

protected void executeSQLQuery(java.lang.String sql,
                               AbstractDomain.RowHandler aRowHandler)

Execute the SQL and pass each row to the given RowHandler. This is a pass-through method that adds the default JDBCHelper to the argument list.

Parameters:

sql - a value of type 'String'

aRowHandler - a value of type 'RowHandler'

executeSQLQuery

protected void executeSQLQuery(java.lang.String sql,
                               AbstractDomain.RowHandler aRowHandler,
                               JDBCHelper aJDBCHelper)

Execute the SQL and pass each row to the given RowHandler.

Parameters:

sql - a value of type 'String'

aRowHandler - a value of type 'RowHandler' - This is an inner class that gets called for each row in the result set.

aJDBCHelper - a value of type 'JDBCHelper'

executeSQLUpdate

protected int executeSQLUpdate(java.lang.String sql)

This is a pass-through method that adds the default JDBCHelper to the argument list.

Parameters:

sql - a value of type 'String'

Returns:

a value of type 'int'

executeSQLUpdate

protected int executeSQLUpdate(java.lang.String sql,
                               JDBCHelper aJDBCHelper)

Execute SQL that updates, deletes, or inserts.

Returns:

a value of type 'int' - number of rows affected.

nextSequence

protected java.lang.Long nextSequence(JDBCHelper aJDBCHelper)

Use JDBC to call a stored procedure to get a the next available sequence id.

Returns:

a value of type 'Long'

findInteger

protected java.lang.Integer findInteger(java.lang.String sql)

This is a pass-through method that adds the default JDBCHelper to the parameter list.

Parameters:

sql - a value of type 'String'

Returns:

a value of type 'Integer'

findInteger

protected java.lang.Integer findInteger(java.lang.String sql,
                                        JDBCHelper aJDBCHelper)

This method calls findLong and casts the result down to an Integer. It is up to the developer to be sure the result will fit into an Integer.

Parameters:

sql - a value of type 'String'

Returns:

a value of type 'Integer'

findLong

protected java.lang.Long findLong(java.lang.String sql)

This is a pass-through method that adds the default JDBCHelper to the parameter list.

Parameters:

sql - a value of type 'String'

Returns:

a value of type 'Long'

findLong

protected java.lang.Long findLong(java.lang.String sql,
                                  JDBCHelper aJDBCHelper)

Execute SQL that returns a Long. This is great for SQL where you just want to get a count of rows, or anything else where all you need from the result set is one Integer.

Parameters:

sql - a value of type 'String'

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'Long'

findCurrentTimestamp

public java.sql.Timestamp findCurrentTimestamp()

Execute SQL that will return the current date and time from the database. This method should only be used when you want to display the database time to the user or something like that. To update a PersistentObject using the current timestamp, put JRFConstants.CURRENT_TIMESTAMP into the object. This is much more efficient.

Returns:

a value of type 'Timestamp'

findCurrentTimestamp

public java.sql.Timestamp findCurrentTimestamp(JDBCHelper aJDBCHelper)

Execute SQL that will find the current timestamp value from the database. This should generally not be used to set a timestamp in an instance that is about to be saved. Instead set that timestamp to JRFConstants.CURRENT_TIMESTAMP before saving. This will save a JDBC call and will be more precise.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

Returns:

a value of type 'Timestamp'

encodePrimaryKey

public java.lang.String encodePrimaryKey(PersistentObject aPO)

Encode the primary key for the given PersistentObject instance as a string that can be decoded later.

Parameters:

aPO - a value of type 'PersistentObject'

Returns:

a value of type 'String'

decodePrimaryKey

public PersistentObject decodePrimaryKey(java.lang.String aString)

Encode the primary key for the given PersistentObject instance as a string that can be decoded later.

Parameters:

aString - a value of type 'String'

Returns:

a value of type 'PersistentObject'

quietlyRollbackAndClose

public void quietlyRollbackAndClose(JDBCHelper aJDBCHelper)

If the rollback doesn't work, we don't need to know about it. Return the JDBCHelper to it's pool if it has one.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

beginTransaction

public void beginTransaction()

This is a pass-through method that adds the default JDBCHelper to the argument list.

beginTransaction

public void beginTransaction(JDBCHelper aJDBCHelper)

This is a helper method that goes with the endTransaction() method.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

endTransaction

public void endTransaction()

This method commits the transaction and closes the JDBCHelper.

See Also:

beginTransaction()

endTransaction

public void endTransaction(JDBCHelper aJDBCHelper)

This method commits the transaction and closes the JDBCHelper. Any unexpected exceptions are rethrown as a DatabaseException. If you don't want the JDBCHelper closed use JDBCHelper#endTransaction() instead.

Parameters:

aJDBCHelper - a value of type 'JDBCHelper'

See Also:

beginTransaction(), endTransaction()

delimitString

public java.lang.String delimitString(java.lang.String aString)

This is a helper method for use by subclasses that are creating SQL. Any single quotes in the string are doubled, and single quotes are placed around the string. Example: param string: "Jonathan's Restaurant" return string: "'Jonathan''s Restaurant'"

Parameters:

aString - a value of type 'String'

Returns:

a value of type 'String'

convertToSubtypePersistentObject

public PersistentObject convertToSubtypePersistentObject(PersistentObject aPO1)

Copy the attribute values from a supertype instance to a subtype instance. Example of when to use this: When converting an Employee supertype instance to a Manager subtype instance.
Manager mgr = managerDomain.convertToSubtypePersistentObject(anEmployee);

Parameters:

aPO - a PersistentObject (this is the supertype instance)

Returns:

a PersistentObject (this is the new subtype instance)

copyAttributes

public void copyAttributes(PersistentObject aPO1,
                           PersistentObject aPO2)

Copy the ColumnSpec attributes from one PersistentObject to another.
Note: If this is a subtype Domain instance then the subtype fields will be copied as well.