com.iplanet.jato.model.sql
Class QueryModelBase

java.lang.Object
  |
  +--com.iplanet.jato.model.DefaultModel
        |
        +--com.iplanet.jato.model.sql.ResultSetModelBase
              |
              +--com.iplanet.jato.model.sql.QueryModelBase
All Implemented Interfaces:
ContextualModel, DatasetModel, DeleteQueryModel, DeletingModel, ExecutingModel, InsertingModel, InsertQueryModel, Model, ModifyingQueryModel, QueryModel, RequestCompletionListener, RequestParticipant, RetrievingDatasetModel, RetrievingModel, SelectQueryModel, java.io.Serializable, SQLModel, UpdateQueryModel, UpdatingModel

public class QueryModelBase
extends ResultSetModelBase
implements QueryModel, RequestParticipant, RequestCompletionListener, java.io.Serializable, SelectQueryModel, DeleteQueryModel, InsertQueryModel, UpdateQueryModel

This class is the core implementation for all SQL query-based models. It is responsible for not only the execution of a given SQL statement, but the general management of where clauses and query results.

This class exists primarily as a value-added feature of the JATO foundation, in that it builds upon standard JDBC to add enhancements and overcome short- comings of that API. If developers prefer to use JDBC directly, we encourage them to do so; however, our intent in providing this class is to allow a much quicker and less SQL-dependent development cycle for developers.

For example, this class provides a standard Model implementation that can be used by the remainder of JATO without knowledge of this class's true type. In addition, this class supports execution control rules that allow developers to specify a range of rows in which they are interested. It also supports the notion of user-scoped WHERE clause qualifiers, and caching iteration through a result set (which greatly helps in those cases where JDBC drivers are very limited in the usage they allow). It also supports optimized use of JDBC drivers, so that tasks such as iteration and location within the result set can be done transparently in the most efficient way. In summary, this class provides a great number of enhancements to vanilla JDBC which would otherwise not be possible to achieve without either very SQL-specific application code, or significant work to duplicate these features.

Simple subclasses of this class could be used directly, in that this class provides all the necessary Model infrastructure. However, developers are encouraged to elaborate such subclasses to provide domain- specific operations (for example, named accessors and mutators) in order to better abstract such models into the business domain, and shield the fact that they rely on SQL (or any other backend that is).

This class assumes that any given model can perform any one of the four standard SQL query operations: select, insert, update, and delete. If a given operation is not supported in a given implementation, methods specific to that operation should remain unimplemented or throw an exception indicating that they are not supported. Users of a SQL-based model who do not wish to use the SQL-specific API should instead rely on the operations specified by the generic-style methods specified in the generic execution interfaces. Common exceptions to such usage are use of the various WHERE criteria methods to add qualifications to a QueryModel's queries. However, to maintain genericity and abstraction from a given data source, we encourage the use of the generic-style methods whenever possible.

Version:
JATO/1.2.2 $Id: QueryModelBase.java,v 1.29 2002/03/16 03:26:33 todd Exp $
See Also:
SelectQueryModel, UpdateQueryModel, InsertQueryModel, DeleteQueryModel, QueryFieldSchema, QueryFieldDescriptor, Serialized Form

Inner Class Summary
static class QueryModelBase.WhereCriterion
          Represents a single WHERE clause criterion.
 
Inner classes inherited from class com.iplanet.jato.model.DefaultModel
DefaultModel.Context, DefaultModel.RowValueArrayList
 
Field Summary
protected static boolean OPTION_CHECK_FOR_EXISTING_USER_WHERE_CRITERIA
          If set, turns on checking for existing WHERE criteria when setting additional WHERE criteria.
protected static boolean OPTION_OPTIMAL_DRIVER_USAGE
          Not currently supported
static int QUERY_TYPE_DELETE
          Identifies a DELETE SQL query
static int QUERY_TYPE_INSERT
          Identifies an INSERT SQL query
static int QUERY_TYPE_SELECT
          Identifies a SELECT SQL query
static int QUERY_TYPE_UPDATE
          Identifies an UPDATE SQL query
 
Fields inherited from class com.iplanet.jato.model.sql.ResultSetModelBase
DEBUG_NEXTROW, DEBUG_POS_RESULTSET, DEBUG_SYNCROW, DEBUG_UPDATE_MODEL, OPTION_COERCE_CACHED_RESULT_SET_VALUES, OPTION_COERCE_VALUE_TYPES, SYNCROW_ALREADY_SYNCHRONIZED, SYNCROW_FOUND_DATA, SYNCROW_NO_MORE_DATA
 
Fields inherited from class com.iplanet.jato.model.DefaultModel
DEFAULT_CONTEXT_NAME, UNDEFINED_ROW_INDEX
 
Constructor Summary
QueryModelBase()
          Default constructor
 
Method Summary
 void addUserWhereCriterion(java.lang.String logicalFieldName, java.lang.Object value)
          Set a field's session-scoped where clause criterion based on the provided value.
 void addUserWhereCriterion(java.lang.String logicalFieldName, java.lang.String operator, java.lang.Object value)
          Set a field's session-scoped where clause criterion based on the provided value.
protected  void afterExecute(ModelExecutionContext context, int queryType)
          Invoked as notification that this model has just successfully completed execution.
protected  java.lang.String beforeExecute(ModelExecutionContext context, int queryType, java.lang.String sql)
          Invoked as notification that this model is about to be executed.
 void clearFieldValueWhereCriteria()
          Removes all fields' request-scoped where clause criteria.
 void clearUserWhereCriteria()
          Removes all fields' session-scoped where clause criteria.
protected  java.lang.String constructDeleteSQL()
          Dynamically constructs a DELETE SQL program using schema information and a dynamically generated WHERE clause
protected  java.lang.String constructInsertSQL()
          Dynamically constructs an INSERT SQL program using schema information
protected  java.lang.String constructSelectSQL()
          Dynamically constructs a SELECT SQL program using the SELECT SQL template and a dynamically generated WHERE clause
protected  java.lang.String constructUpdateSQL()
          Dynamically constructs an UPDATE SQL program using schema information and a dynamically generated WHERE clause
 java.lang.Object delete(ModelExecutionContext context)
          Executes this model in deleting mode.
protected  java.lang.String escapeSingleQuotes(java.lang.String value)
          Escapes single quotes in the provided value with doubled single quotes
 java.lang.Object execute(ModelExecutionContext context)
          Execute the model.
 int executeDelete(ModelExecutionContext context)
          Executes the model in deleting mode, using the provided execution context
 int executeInsert(ModelExecutionContext context)
          Executes the model in inserting mode, using the provided execution context
 java.sql.ResultSet executeSelect(DatasetModelExecutionContext context)
          Executes the model in retrieving/select mode, using the provided execution context
 int executeUpdate(ModelExecutionContext context)
          Executes the model in updating mode, using the provided execution context
 java.lang.String getDataSourceName()
          Returns the logical name of the SQL datasource this model uses.
 java.sql.Connection getDefaultConnection()
          Returns a default JDBC connection.
 java.lang.String getDefaultConnectionPassword()
          Return the password that will be used when allocating a default JDBC connection.
 java.lang.String getDefaultConnectionUser()
          Return the username that will be used when allocating a default JDBC connection.
 java.lang.String getDeleteSQL()
          Returns the developer-specified DELETE SQL program, or if no SQL program has been specified, returns a program constructed dynamically
 java.lang.String getDelimitedTableNames()
          Deprecated. The name of this method is misleading since it is only used with queries that operate against a single table. Instead, use the getModifyingQueryTableName() method.
protected  java.util.Map getFieldValueWhereCriteria(boolean createIfNeeded)
          This method is for internal use.
 java.lang.String getFieldValueWhereCriteriaString()
          This method is for internal use.
protected  java.lang.Object getInsertQueryValue(java.lang.String fieldName)
          Returns a value for inclusion in the INSERT query currently being constructed.
 java.lang.String getInsertSQL()
          Returns the developer-specified INSERT SQL program, or if no SQL program has been specified, returns a program constructed dynamically
 java.lang.String getModifyingQueryTableName()
          Returns the name of the table to be used during modifying (INSERT, UPDATE, DELETE) queries
 int getNumAffectedRows()
          Returns the number of rows affected by the most recently executed query.
 RequestContext getRequestContext()
          Returns the current request context
 java.lang.String getSelectSQL()
          Returns the developer-specified SELECT SQL program, or if no SQL program has been specified, returns a program constructed dynamically using the SELECT SQL template
 java.lang.String getSelectSQLTemplate()
          Return the SELECT query SQL program template used for SELECT queries.
 java.lang.String getSelectSQLTemplateWhereToken()
          Returns the token used to specify the WHERE clause location within the SELECT SQL program template.
 java.lang.String getSQL(int type)
          Provides a covenient single location through which all requests for SQL statements in this implementation are funnelled.
 java.lang.String getStaticWhereCriteriaString()
          Returns the developer-provided static WHERE criteria used to construct the full WHERE clause using in dynamically generated queries (where the full WHERE clause consists of static criteria plus various types of dynamically generated criteria)
 boolean getTraceSQL()
          Returns the state of SQL tracing.
protected  java.lang.Object getUpdateQueryValue(java.lang.String fieldName)
          Returns a value for inclusion in the UPDATE query currently being constructed.
 java.lang.String getUpdateSQL()
          Returns the developer-specified UPDATE SQL program, or if no SQL program has been specified, returns a program constructed dynamically
protected  java.util.List getUserWhereCriteria(boolean createIfNeeded)
          This method is for internal use.
protected  java.lang.String getUserWhereCriteriaSessionKey()
          This method is for internal use.
 java.lang.String getUserWhereCriteriaString()
          This method is for internal use.
 java.lang.String getWhereClause()
          Returns the full WHERE clause used by this class in dynamically generated queries.
 java.lang.String getWhereClauseOverride()
          Returns the full replacement WHERE clause that will be used by this class in dynamically generated queries instead of a dynamically generated WHERE clause returned by getWhereClause()
 boolean hasUserWhereCriterion(java.lang.String logicalFieldName, java.lang.String operator, java.lang.Object value)
          Checks whether a matching WHERE criterion already exists NOTE:
This implementation is currently quite inefficient when large numbers of user criteria are being used.
 java.lang.Object insert(ModelExecutionContext context)
          Executes this model in inserting mode.
protected  void onDatabaseError(ModelExecutionContext context, int queryType, java.sql.SQLException exception)
          Invoked as notification that this model encountered a SQLException.
 void removeFieldValueWhereCriterion(java.lang.String logicalFieldName)
          Removes a field's request-scoped where clause criterion.
 void removeUserWhereCriteria(java.lang.String logicalFieldName)
          Removes all of a field's session-scoped where clause criteria.
 void requestComplete()
          Called to notify the listener that the request is at an end
protected  void restoreSessionedUserWhereCriteria(RequestContext requestContext)
          This method is for internal use.
 java.lang.Object retrieve(ModelExecutionContext context)
          Executes this model in retrieving mode.
 void setDataSourceName(java.lang.String value)
          Sets the logical name of the SQL datasource this model uses.
 void setDefaultConnectionPassword(java.lang.String value)
          Set the password that will be used when allocating a default JDBC connection.
 void setDefaultConnectionUser(java.lang.String value)
          Set the username that will be used when allocating a default JDBC connection.
 void setDeleteSQL(java.lang.String value)
          Allows the developer to specify the SQL progam used for DELETE queries.
 void setDelimitedTableNames(java.lang.String value)
          Deprecated. The name of this method is misleading since it is only used with queries that operate against a single table. Instead, use the setModifyingQueryTableName(String) method.
 void setFieldValueWhereCriterion(java.lang.String logicalFieldName)
          Set a field's request-scoped where clause criterion based on the field's value.
 void setFieldValueWhereCriterion(java.lang.String logicalFieldName, java.lang.String operator)
          Set a field's request-scoped where clause criterion based on the field's value.
 void setInsertSQL(java.lang.String value)
          Allows the developer to specify the SQL progam used for INSERT queries.
 void setModifyingQueryTableName(java.lang.String value)
          Sets the name of the table to be used during modifying (INSERT, UPDATE, DELETE) queries
protected  void setNumAffectedRows(int value)
          Sets the number of rows affected by the most recently executed query.
 void setRequestContext(RequestContext value)
          Sets the request context
 void setSelectSQL(java.lang.String value)
          Allows the developer to specify the SQL progam used for SELECT queries.
 void setSelectSQLTemplate(java.lang.String value)
          Sets the SELECT query SQL program template used for SELECT queries.
 void setSelectSQLTemplateWhereToken(java.lang.String value)
          Sets the token used to specify the WHERE clause location within the SELECT SQL program template.
 void setStaticWhereCriteriaString(java.lang.String value)
          Sets the developer-provided static WHERE criteria used to construct the full WHERE clause using in dynamically generated queries (where the full WHERE clause consists of static criteria plus various types of dynamically generated criteria)
 void setTraceSQL(boolean value)
          Sets the state of SQL tracing.
 void setUpdateSQL(java.lang.String value)
          Allows the developer to specify the SQL progam used for UPDATE queries.
 void setWhereClauseOverride(java.lang.String value)
          Sets the full replacement WHERE clause that will be used by this class in dynamically generated queries instead of a dynamically generated WHERE clause returned by getWhereClause()
protected  boolean shouldQuoteType(java.lang.Class columnClass)
          Override to indicate if a column specific type should be quoted.
protected  boolean shouldQuoteValue(java.lang.Class columnClass)
          Deprecated. This method has changed name to be more descriptive of its function. Please use the shouldQuoteType() method instead.
protected  void storeSessionedUserWhereCriteria(RequestContext requestContext)
          This method is for internal use.
 java.lang.Object update(ModelExecutionContext context)
          Executes this model in updating mode.
 
Methods inherited from class com.iplanet.jato.model.sql.ResultSetModelBase
beforeFirst, clear, clearResultSet, first, getFieldClass, getFieldSchema, getLocation, getLocationOffset, getResultSet, getSize, getValueMap, hasMoreResults, hasPreviousResults, hasValue, last, next, positionResultSet, positionResultSet, previous, resolveResultSetColumnSet, setFieldSchema, setLocation, setLocationOffset, setMoreResults, setPreviousResults, setResultSet, setSize, setValue, setValues, synchronizeRow, updateModel
 
Methods inherited from class com.iplanet.jato.model.DefaultModel
addContext, appendRow, checkRowIndex, clearModelData, createValueMap, dumpValues, dumpValues, ensureRow, getContext, getContextNames, getCurrentContext, getCurrentContextName, getDefaultValue, getDefaultValueMap, getDefaultValues, getName, getNumRows, getRowIndex, getRowList, getValue, getValueMap, getValues, initializeDefaultContext, insertRow, isDefaultContext, isUseDefaultValues, removeContext, selectContext, selectDefaultContext, setDefaultValue, setDefaultValues, setName, setNumRows, setRowIndex, setRowList, setUseDefaultValues
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.iplanet.jato.model.sql.QueryModel
getFieldSchema
 
Methods inherited from interface com.iplanet.jato.model.Model
getName, getValue, getValues, setName, setValue, setValues
 
Methods inherited from interface com.iplanet.jato.model.sql.SelectQueryModel
getResultSet
 
Methods inherited from interface com.iplanet.jato.model.DatasetModel
beforeFirst, first, getLocation, getLocationOffset, getSize, last, next, previous, setLocation, setSize
 

Field Detail

QUERY_TYPE_SELECT

public static final int QUERY_TYPE_SELECT
Identifies a SELECT SQL query

QUERY_TYPE_INSERT

public static final int QUERY_TYPE_INSERT
Identifies an INSERT SQL query

QUERY_TYPE_UPDATE

public static final int QUERY_TYPE_UPDATE
Identifies an UPDATE SQL query

QUERY_TYPE_DELETE

public static final int QUERY_TYPE_DELETE
Identifies a DELETE SQL query

OPTION_OPTIMAL_DRIVER_USAGE

protected static final boolean OPTION_OPTIMAL_DRIVER_USAGE
Not currently supported

OPTION_CHECK_FOR_EXISTING_USER_WHERE_CRITERIA

protected static final boolean OPTION_CHECK_FOR_EXISTING_USER_WHERE_CRITERIA
If set, turns on checking for existing WHERE criteria when setting additional WHERE criteria. This is generally only a debugging aid and not useful in deployment.
Constructor Detail

QueryModelBase

public QueryModelBase()
Default constructor
Method Detail

getDataSourceName

public java.lang.String getDataSourceName()
Returns the logical name of the SQL datasource this model uses. This name can be arbitrary, but should generally be of the JNDI form described in the JDBC 2.0 Standard Extension specification, for use within a J2EE-compliant container; for example, jdbc/MyDataSource or jdbc/MyApp/MyDataSource
Specified by:
getDataSourceName in interface SQLModel
Returns:
The logical datasource name

setDataSourceName

public void setDataSourceName(java.lang.String value)
Sets the logical name of the SQL datasource this model uses. This name can be arbitrary, but should generally be of the JNDI form described in the JDBC 2.0 Standard Extension specification, for use within a J2EE-compliant container; for example, jdbc/MyDataSource or jdbc/MyApp/MyDataSource
Parameters:
value - The logical datasource name

getTraceSQL

public boolean getTraceSQL()
Returns the state of SQL tracing. To view the tracing, logging at the Log.JATO_TRACE level must be enabled. To send the tracing in System.out, call setEchoToSystemOut(true) somewhere during application initialization.
Returns:
true if SQL statements will be traced to System.out
Since:
JATO/1.2

setTraceSQL

public void setTraceSQL(boolean value)
Sets the state of SQL tracing. To view the tracing, logging at the Log.JATO_TRACE level must be enabled. To send the tracing in System.out, call setEchoToSystemOut(true) somewhere during application initialization.
Parameters:
value - true if SQL statements will be traced to System.out
Since:
JATO/1.2

getSQL

public java.lang.String getSQL(int type)
Provides a covenient single location through which all requests for SQL statements in this implementation are funnelled. This fact allows the developer to effect global changes to SQL statements at the last second, or trace SQL statements in the form in which they are sent to the database. If a client wants to obtain a particular SQL statement directly, he need not use this method to do so and can instead call one of the type-specific methods directly.
Parameters:
type - The SQL statement type, one of QUERY_TYPE_SELECT, QUERY_TYPE_INSERT, QUERY_TYPE_UPDATE, or QUERY_TYPE_DELETE
Returns:
The requested SQL statement
See Also:
getSelectSQL(), getInsertSQL(), getUpdateSQL(), getDeleteSQL()

getSelectSQLTemplate

public java.lang.String getSelectSQLTemplate()
Return the SELECT query SQL program template used for SELECT queries. The template consists of a standard SELECT SQL program but without a WHERE clause, which this class will construct dynamically. The location at which to insert the WHERE clause in the SQL program should be specified by the token returned by the getSelectSQLTemplateWhereToken() method (the default value is __WHERE__). For example:
	SELECT * FROM Foo __WHERE__
	SELECT * FROM Foo __WHERE__ ORDER BY Foo.BAR
 
In order to perform SELECT queries using this class, the SELECT SQL template must be specified (the reason for this is that unlike the other query types, the SELECT query program can be arbitrarily complex, including joins from tables that are outside of the knowledge of this model).
Returns:
The SELECT SQL program template

setSelectSQLTemplate

public void setSelectSQLTemplate(java.lang.String value)
Sets the SELECT query SQL program template used for SELECT queries. The template consists of a standard SELECT SQL program but without a WHERE clause, which this class will construct dynamically. The location at which to insert the WHERE clause in the SQL program should be specified by the token returned by the getSelectSQLTemplateWhereToken() method (the default value is __WHERE__). For example:
	SELECT * FROM Foo __WHERE__
	SELECT * FROM Foo __WHERE__ ORDER BY Foo.BAR
 
In order to perform SELECT queries using this class, the SELECT SQL template must be specified (the reason for this is that unlike the other query types, the SELECT query program can be arbitrarily complex, including joins from tables that are outside of the knowledge of this model).
Parameters:
value - The SELECT SQL program template

getSelectSQLTemplateWhereToken

public java.lang.String getSelectSQLTemplateWhereToken()
Returns the token used to specify the WHERE clause location within the SELECT SQL program template. The default value of this token is __WHERE__.
Returns:
The WHERE clause token string

setSelectSQLTemplateWhereToken

public void setSelectSQLTemplateWhereToken(java.lang.String value)
Sets the token used to specify the WHERE clause location within the SELECT SQL program template. The default value of this token is __WHERE__.
Parameters:
value - The WHERE clause token string

getSelectSQL

public java.lang.String getSelectSQL()
Returns the developer-specified SELECT SQL program, or if no SQL program has been specified, returns a program constructed dynamically using the SELECT SQL template

setSelectSQL

public void setSelectSQL(java.lang.String value)
Allows the developer to specify the SQL progam used for SELECT queries. If the SQL program is notspecified, this class will dynamically construct an appropriate SQL program using the SELECT query template
Parameters:
value - The SQL program to be used for this type of query, or null if the model should dynamically construct its own SQL program
See Also:
getSelectSQLTemplate(), setSelectSQLTemplate(String)

getInsertSQL

public java.lang.String getInsertSQL()
Returns the developer-specified INSERT SQL program, or if no SQL program has been specified, returns a program constructed dynamically

setInsertSQL

public void setInsertSQL(java.lang.String value)
Allows the developer to specify the SQL progam used for INSERT queries. If the SQL program is notspecified, this class will dynamically construct an appropriate SQL program.
Parameters:
value - The SQL program to be used for this type of query, or null if the model should dynamically construct its own SQL program

getUpdateSQL

public java.lang.String getUpdateSQL()
Returns the developer-specified UPDATE SQL program, or if no SQL program has been specified, returns a program constructed dynamically

setUpdateSQL

public void setUpdateSQL(java.lang.String value)
Allows the developer to specify the SQL progam used for UPDATE queries. If the SQL program is notspecified, this class will dynamically construct an appropriate SQL program.
Parameters:
value - The SQL program to be used for this type of query, or null if the model should dynamically construct its own SQL program

getDeleteSQL

public java.lang.String getDeleteSQL()
Returns the developer-specified DELETE SQL program, or if no SQL program has been specified, returns a program constructed dynamically

setDeleteSQL

public void setDeleteSQL(java.lang.String value)
Allows the developer to specify the SQL progam used for DELETE queries. If the SQL program is notspecified, this class will dynamically construct an appropriate SQL program.
Parameters:
value - The SQL program to be used for this type of query, or null if the model should dynamically construct its own SQL program

execute

public java.lang.Object execute(ModelExecutionContext context)
                         throws ModelControlException
Description copied from interface: ExecutingModel
Execute the model. The execution context may contain an operation name that specifies the particular operation to execute.
Specified by:
execute in interface ExecutingModel
Following copied from interface: com.iplanet.jato.model.ExecutingModel
Parameters:
context - The execution context that specifies detail information pertinent to the execution of this model
Returns:
An opaque implementation-dependent object encapsulating information related to the execution of this method
Throws:
ModelControlException - Thrown if an error occurs executing the model

retrieve

public java.lang.Object retrieve(ModelExecutionContext context)
                          throws ModelControlException
Executes this model in retrieving mode. This method is designed to be called by callers that do not know the specific type of this model, or who want to use this model in a generic fashion. Compare this method to the executeSelect(...) method, which requires knowledge that this object is a SQL-based model. However, in effect, these two methods are equivalent and only differ in type specificity. Developers should feel free to use whichever method they prefer; but, we do urge generic use of models unless use of type-specific features is required.
Specified by:
retrieve in interface RetrievingModel
See Also:
executeSelect(DatasetModelExecutionContext)

insert

public java.lang.Object insert(ModelExecutionContext context)
                        throws ModelControlException
Executes this model in inserting mode. This method is designed to be called by callers that do not know the specific type of this model, or who want to use this model in a generic fashion. Compare this method to the executeInsert(...) method, which requires knowledge that this object is a SQL-based model. However, in effect, these two methods are equivalent and only differ in type specificity. Developers should feel free to use whichever method they prefer; but, we do urge generic use of models unless use of type-specific features is required.
Specified by:
insert in interface InsertingModel
See Also:
executeInsert(ModelExecutionContext)

update

public java.lang.Object update(ModelExecutionContext context)
                        throws ModelControlException
Executes this model in updating mode. This method is designed to be called by callers that do not know the specific type of this model, or who want to use this model in a generic fashion. Compare this method to the executeUpdate(...) method, which requires knowledge that this object is a SQL-based model. However, in effect, these two methods are equivalent and only differ in type specificity. Developers should feel free to use whichever method they prefer; but, we do urge generic use of models unless use of type-specific features is required.
Specified by:
update in interface UpdatingModel
See Also:
executeUpdate(ModelExecutionContext)

delete

public java.lang.Object delete(ModelExecutionContext context)
                        throws ModelControlException
Executes this model in deleting mode. This method is designed to be called by callers that do not know the specific type of this model, or who want to use this model in a generic fashion. Compare this method to the executeDelete(...) method, which requires knowledge that this object is a SQL-based model. However, in effect, these two methods are equivalent and only differ in type specificity. Developers should feel free to use whichever method they prefer; but, we do urge generic use of models unless use of type-specific features is required.
Specified by:
delete in interface DeletingModel
See Also:
executeDelete(ModelExecutionContext)

getDelimitedTableNames

public java.lang.String getDelimitedTableNames()
Deprecated. The name of this method is misleading since it is only used with queries that operate against a single table. Instead, use the getModifyingQueryTableName() method.


setDelimitedTableNames

public void setDelimitedTableNames(java.lang.String value)
Deprecated. The name of this method is misleading since it is only used with queries that operate against a single table. Instead, use the setModifyingQueryTableName(String) method.


getModifyingQueryTableName

public java.lang.String getModifyingQueryTableName()
Returns the name of the table to be used during modifying (INSERT, UPDATE, DELETE) queries
Returns:
The table name as understood by the target database

setModifyingQueryTableName

public void setModifyingQueryTableName(java.lang.String value)
Sets the name of the table to be used during modifying (INSERT, UPDATE, DELETE) queries
Parameters:
value - The table name as understood by the target database

shouldQuoteType

protected boolean shouldQuoteType(java.lang.Class columnClass)
Override to indicate if a column specific type should be quoted. If overridden, always call the superclass version of this method and check its result first.
Parameters:
The - field type that could be potentially quoted
Returns:
true if this class should quote values of this type during SQL generation

shouldQuoteValue

protected boolean shouldQuoteValue(java.lang.Class columnClass)
Deprecated. This method has changed name to be more descriptive of its function. Please use the shouldQuoteType() method instead.

Override to indicate if a column specific type should be quoted

constructSelectSQL

protected java.lang.String constructSelectSQL()
Dynamically constructs a SELECT SQL program using the SELECT SQL template and a dynamically generated WHERE clause
Returns:
The ready-to-execute SQL program

constructInsertSQL

protected java.lang.String constructInsertSQL()
Dynamically constructs an INSERT SQL program using schema information
Returns:
The ready-to-execute SQL program

getInsertQueryValue

protected java.lang.Object getInsertQueryValue(java.lang.String fieldName)
Returns a value for inclusion in the INSERT query currently being constructed. This value may be overidden by developers to perform last- second transformations on values used in a query, for example, turning a value into a database-specific formula. This method is called just before the specified field is included in the query string, and is not expected to modify the value stored in the model. Note, this method should not return null if the hasValue() method has previously returned true for the field.
Parameters:
fieldName - The logical field name of the required value
Returns:
The value, transformed if appropriate

constructUpdateSQL

protected java.lang.String constructUpdateSQL()
Dynamically constructs an UPDATE SQL program using schema information and a dynamically generated WHERE clause
Returns:
The ready-to-execute SQL program

getUpdateQueryValue

protected java.lang.Object getUpdateQueryValue(java.lang.String fieldName)
Returns a value for inclusion in the UPDATE query currently being constructed. This value may be overidden by developers to perform last- second modifications on values used in a query, for example, turning a value into a database-specific formula. This method is called just before the specified field is included in the query string, and is not expected to modify the value stored in the model. Note, this method should not return null if the hasValue() method has previously returned true for the field.
Parameters:
fieldName - The logical field name of the required value
Returns:
The value, transformed if appropriate

constructDeleteSQL

protected java.lang.String constructDeleteSQL()
Dynamically constructs a DELETE SQL program using schema information and a dynamically generated WHERE clause
Returns:
The ready-to-execute SQL program

escapeSingleQuotes

protected java.lang.String escapeSingleQuotes(java.lang.String value)
Escapes single quotes in the provided value with doubled single quotes
Returns:
The escaped value string

getStaticWhereCriteriaString

public java.lang.String getStaticWhereCriteriaString()
Returns the developer-provided static WHERE criteria used to construct the full WHERE clause using in dynamically generated queries (where the full WHERE clause consists of static criteria plus various types of dynamically generated criteria)
Returns:
The static WHERE criteria to be included after the "WHERE" keyword and before any dynamically generated WHERE criteria

setStaticWhereCriteriaString

public void setStaticWhereCriteriaString(java.lang.String value)
Sets the developer-provided static WHERE criteria used to construct the full WHERE clause using in dynamically generated queries (where the full WHERE clause consists of static criteria plus various types of dynamically generated criteria)
Parameters:
value - The static WHERE criteria to be included after the "WHERE" keyword and before any dynamically generated WHERE criteria

getWhereClause

public java.lang.String getWhereClause()
Returns the full WHERE clause used by this class in dynamically generated queries. The WHERE clause consists of static criteria plus various types of dynamicaly generated criteria.
Returns:
The full WHERE clause
See Also:
getStaticWhereCriteriaString()

getWhereClauseOverride

public java.lang.String getWhereClauseOverride()
Returns the full replacement WHERE clause that will be used by this class in dynamically generated queries instead of a dynamically generated WHERE clause returned by getWhereClause()
Returns:
The full replacement WHERE clause

setWhereClauseOverride

public void setWhereClauseOverride(java.lang.String value)
Sets the full replacement WHERE clause that will be used by this class in dynamically generated queries instead of a dynamically generated WHERE clause returned by getWhereClause()
Returns:
The full replacement WHERE clause

getFieldValueWhereCriteriaString

public java.lang.String getFieldValueWhereCriteriaString()
This method is for internal use.

getFieldValueWhereCriteria

protected java.util.Map getFieldValueWhereCriteria(boolean createIfNeeded)
This method is for internal use.

setFieldValueWhereCriterion

public void setFieldValueWhereCriterion(java.lang.String logicalFieldName)
Description copied from interface: SelectQueryModel
Set a field's request-scoped where clause criterion based on the field's value. The criterion will use the equality operator to designate that the field's value should be exactly equal to the value specified in the model.

This method is used in the construction of so-called late-bound criteria, in which the specification of a field to be ultimately used in the where clause can be specified at any any time (from the beginning of the request), but the value actually used in the where clause is the value present in the model at where clause construction time. This allows the value to change during the lifetime of the request, and its use in the where clause to be specified by a section of code that may not be responsible for ultimately setting the value.

Note that only one field value criterion can be set per field in the model; because the value to be used in the where clause is ultimately based on the value present in the model at where clause construction time, calling this method repeatedly has no additional effect other than to possibly override the relational operator set for this criterion. For example, field value criteria cannot be used to specify range criteria.

Specified by:
setFieldValueWhereCriterion in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.
See Also:
Model.setValue(String, Object), Model.setValues(String, Object[])

setFieldValueWhereCriterion

public void setFieldValueWhereCriterion(java.lang.String logicalFieldName,
                                        java.lang.String operator)
Description copied from interface: SelectQueryModel
Set a field's request-scoped where clause criterion based on the field's value. The criterion will use the relational operator provided by the caller to later construct the criterion.

This method is used in the construction of so-called late-bound criteria, in which the specification of a field to be ultimately used in the where clause can be specified at any any time (from the beginning of the request), but the value actually used in the where clause is the value present in the model at where clause construction time. This allows the value to change during the lifetime of the request, and its use in the where clause to be specified by a section of code that may not be responsible for ultimately setting the value.

Note that only one field value criterion can be set per field in the model; because the value to be used in the where clause is ultimately based on the value present in the model at where clause construction time, calling this method repeatedly has no additional effect other than to possibly override the relational operator set for this criterion. For example, field value criteria cannot be used to specify range criteria.

Specified by:
setFieldValueWhereCriterion in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.
operator - The operator to be used in construction of the criterion. Generally, this will be a values like "=", "<", or ">=" but may be database dependent.
See Also:
Model.setValue(String, Object), Model.setValues(String, Object[])

removeFieldValueWhereCriterion

public void removeFieldValueWhereCriterion(java.lang.String logicalFieldName)
Description copied from interface: SelectQueryModel
Removes a field's request-scoped where clause criterion. The field's value will not be used to generate a criterion during where clause construction.

This method is used in the construction of so-called late-bound criteria, in which the specification of a field to be ultimately used in the where clause can be specified at any any time (from the beginning of the request), but the value actually used in the where clause is the value present in the model at where clause construction time. This allows the value to change during the lifetime of the request, and its use in the where clause to be specified by a section of code that may not be responsible for ultimately setting the value.

Specified by:
removeFieldValueWhereCriterion in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.

clearFieldValueWhereCriteria

public void clearFieldValueWhereCriteria()
Description copied from interface: SelectQueryModel
Removes all fields' request-scoped where clause criteria. The fields' values will not be used to generate criteria during where clause construction. However, user where criteria remain in effect after this method is called.
Specified by:
clearFieldValueWhereCriteria in interface SelectQueryModel

getUserWhereCriteriaString

public java.lang.String getUserWhereCriteriaString()
This method is for internal use.

getUserWhereCriteria

protected java.util.List getUserWhereCriteria(boolean createIfNeeded)
This method is for internal use.

addUserWhereCriterion

public void addUserWhereCriterion(java.lang.String logicalFieldName,
                                  java.lang.Object value)
Description copied from interface: SelectQueryModel
Set a field's session-scoped where clause criterion based on the provided value. The criterion will use the equality operator to designate that the field's value should be exactly equal to the specified value.

This method is used in the construction of so-called early-bound criteria, in which field value constraints can be specified multiple times with different target values and relational operators. Thus, multiple sections of code can add independent where criteria, each potentially targeting the same field, which will all be used during where clause construction.

Note that multple user criteria can be set per field; because the value to be used in the where clause is specified when this method is called and cannot later be changed, calling this method repeatedly adds additional criteria, even if the same field is specified as the target. For example, user where criteria can be used to specify a query range by adding two seperate boundary criteria.

Note that an implementation is under no obligation to ensure that multiple user criteria are not mutually exclusive. Therefore, use caution when setting mutiple user criteria. Also note that because user where criteria are saved in the user's session, they are present across requests. Therefore, developers must clear user criteria when appropriate to ensure that they do not conflict over time. Finally, note that user where criteria are user- and model-specific; the same criterion cannot apply to more than one model.

Specified by:
addUserWhereCriterion in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.
value - The value of the field to specify in the criterion

addUserWhereCriterion

public void addUserWhereCriterion(java.lang.String logicalFieldName,
                                  java.lang.String operator,
                                  java.lang.Object value)
Description copied from interface: SelectQueryModel
Set a field's session-scoped where clause criterion based on the provided value. The criterion will use the relational operator provided by the caller to construct the criterion.

This method is used in the construction of so-called early-bound criteria, in which field value constraints can be specified multiple times with different target values and relational operators. Thus, multiple sections of code can add independent where criteria, each potentially targeting the same field, which will all be used during where clause construction.

Note that multple user criteria can be set per field; because the value to be used in the where clause is specified when this method is called and cannot later be changed, calling this method repeatedly adds additional criteria, even if the same field is specified as the target. For example, user where criteria can be used to specify a query range by adding two seperate boundary criteria.

Note that an implementation is under no obligation to ensure that multiple user criteria are not mutually exclusive. Therefore, use caution when setting mutiple user criteria. Also note that because user where criteria are saved in the user's session, they are present across requests. Therefore, developers must clear user criteria when appropriate to ensure that they do not conflict over time. Finally, note that user where criteria are user- and model-specific; the same criterion cannot apply to more than one model.

Specified by:
addUserWhereCriterion in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.
operator - The operator to be used in construction of the criterion. Generally, this will be a values like "=", "<", or ">=" but may be database dependent.
value - The value of the field to specify in the criterion

hasUserWhereCriterion

public boolean hasUserWhereCriterion(java.lang.String logicalFieldName,
                                     java.lang.String operator,
                                     java.lang.Object value)
Checks whether a matching WHERE criterion already exists NOTE:
This implementation is currently quite inefficient when large numbers of user criteria are being used. Avoid using if possible in such circumstances.
Specified by:
hasUserWhereCriterion in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.
operator - The operator to be used in construction of the criterion. Generally, this will be a values like "=", "<", or ">=" but may be database dependent.
value - The value of the field to specify in the criterion
Returns:
True if a matching criterion exists, false if not

removeUserWhereCriteria

public void removeUserWhereCriteria(java.lang.String logicalFieldName)
Description copied from interface: SelectQueryModel
Removes all of a field's session-scoped where clause criteria. No criteria for this field will be used during where clause construction.

This method is used in the construction of so-called early-bound criteria, in which field value constraints can be specified multiple times with different target values and relational operators. Thus, multiple sections of code can add independent where criteria, each potentially targeting the same field, which will all be used during where clause construction.

Note that multple user criteria can be set per field; this method removes all criteria for the name field.

Specified by:
removeUserWhereCriteria in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
logicalFieldName - The logical field name in this model. This name is generally mapped to the physical column by the implementation.

clearUserWhereCriteria

public void clearUserWhereCriteria()
Description copied from interface: SelectQueryModel
Removes all fields' session-scoped where clause criteria. No such criteria will be used during where clause construction. However, field value criteria remain in effect after this method is called.
Specified by:
clearUserWhereCriteria in interface SelectQueryModel

getUserWhereCriteriaSessionKey

protected java.lang.String getUserWhereCriteriaSessionKey()
This method is for internal use.

storeSessionedUserWhereCriteria

protected void storeSessionedUserWhereCriteria(RequestContext requestContext)
This method is for internal use.

restoreSessionedUserWhereCriteria

protected void restoreSessionedUserWhereCriteria(RequestContext requestContext)
This method is for internal use.

getRequestContext

public RequestContext getRequestContext()
Returns the current request context
Returns:
The request context for the current servlet request

setRequestContext

public void setRequestContext(RequestContext value)
Description copied from interface: RequestParticipant
Sets the request context
Specified by:
setRequestContext in interface RequestParticipant
Following copied from interface: com.iplanet.jato.RequestParticipant
Parameters:
requestContext - The request context of the current request

requestComplete

public void requestComplete()
Description copied from interface: RequestCompletionListener
Called to notify the listener that the request is at an end
Specified by:
requestComplete in interface RequestCompletionListener

beforeExecute

protected java.lang.String beforeExecute(ModelExecutionContext context,
                                         int queryType,
                                         java.lang.String sql)
                                  throws ModelControlException
Invoked as notification that this model is about to be executed. The reason this and similar methods exist is to provide the subclass developer a chance to perform model-specific pre-execution logic. This method is invoked regardless of the mode of model execution. The default implementation of this method simply allows the execution to proceed.
Parameters:
context - The ModelExecutionContext specific to the current execution.
queryType - The SQL statement type, one of QUERY_TYPE_SELECT, QUERY_TYPE_INSERT, QUERY_TYPE_UPDATE, or QUERY_TYPE_DELETE.
sql - The SQL program.
Returns:
The SQL program
Throws:
ModelControlException -  

afterExecute

protected void afterExecute(ModelExecutionContext context,
                            int queryType)
                     throws ModelControlException
Invoked as notification that this model has just successfully completed execution. The reason this and similar methods exist is to provide the subclass developer a chance to perform model-specific post-execution logic. This method is only invoked following a successful execution. If the execution resulted in a SQL exception, then onDatabaseError is invoked instead.
Parameters:
context - The ModelExecutionContext specific to the current execution.
queryType - The SQL statement type, one of QUERY_TYPE_SELECT, QUERY_TYPE_INSERT, QUERY_TYPE_UPDATE, or QUERY_TYPE_DELETE.
Throws:
ModelControlException -  

onDatabaseError

protected void onDatabaseError(ModelExecutionContext context,
                               int queryType,
                               java.sql.SQLException exception)
Invoked as notification that this model encountered a SQLException. The reason this and similar methods exist is to provide the subclass developer a chance to perform model-specific error handling logic.
Parameters:
context - The ModelExecutionContext specific to the current execution.
queryType - The SQL statement type, one of QUERY_TYPE_SELECT, QUERY_TYPE_INSERT, QUERY_TYPE_UPDATE, or QUERY_TYPE_DELETE.
exception - The SQLException.

getDefaultConnection

public java.sql.Connection getDefaultConnection()
                                         throws java.sql.SQLException
Returns a default JDBC connection. The default connection will be used if no explicit connection is provided at model execution time via a SQLModelExecutionContext.

getDefaultConnectionUser

public java.lang.String getDefaultConnectionUser()
Return the username that will be used when allocating a default JDBC connection. This username will not be used if a connection or statement is provided during execution.

setDefaultConnectionUser

public void setDefaultConnectionUser(java.lang.String value)
Set the username that will be used when allocating a default JDBC connection. This username will not be used if a connection or statement is provided during execution. A value of null will result in a username & password not being used when obtaining a default connection. Note: this value may not be necessary if the JDBC connection string or JDBC DataSource includes or has already been configured to use a username & password.
Parameters:
value - A valid username, or null to disable use of a username & password when obtaining a default connection

getDefaultConnectionPassword

public java.lang.String getDefaultConnectionPassword()
Return the password that will be used when allocating a default JDBC connection. This password will not be used if a connection or statement is provided during execution.

setDefaultConnectionPassword

public void setDefaultConnectionPassword(java.lang.String value)
Set the password that will be used when allocating a default JDBC connection. This password will not be used if a connection or statement is provided during execution. Note: this value may not be necessary if the JDBC connection string or JDBC DataSource includes or has already been configured to use a username & password.
Parameters:
value - A valid password for the current default connection user

executeSelect

public java.sql.ResultSet executeSelect(DatasetModelExecutionContext context)
                                 throws java.sql.SQLException,
                                        ModelControlException
Description copied from interface: SelectQueryModel
Executes the model in retrieving/select mode, using the provided execution context
Specified by:
executeSelect in interface SelectQueryModel
Following copied from interface: com.iplanet.jato.model.sql.SelectQueryModel
Parameters:
context - The execution context to be used during the execution of this query
Returns:
The result set resulting from the execution. The result set returned by this method is generally also available via the getResultSet() method.

executeUpdate

public int executeUpdate(ModelExecutionContext context)
                  throws java.sql.SQLException,
                         ModelControlException
Description copied from interface: UpdateQueryModel
Executes the model in updating mode, using the provided execution context
Specified by:
executeUpdate in interface UpdateQueryModel
Following copied from interface: com.iplanet.jato.model.sql.UpdateQueryModel
Parameters:
context - The execution context to be used during the execution of this query. This parameter cannot be null or an java.lang.IllegalArgumentException will be thrown.
Returns:
The number of rows in the database affected by this query

executeInsert

public int executeInsert(ModelExecutionContext context)
                  throws java.sql.SQLException,
                         ModelControlException
Description copied from interface: InsertQueryModel
Executes the model in inserting mode, using the provided execution context
Specified by:
executeInsert in interface InsertQueryModel
Following copied from interface: com.iplanet.jato.model.sql.InsertQueryModel
Parameters:
context - The execution context to be used during the execution of this query. This parameter cannot be null or an java.lang.IllegalArgumentException will be thrown.
Returns:
The number of rows in the database affected by this query

executeDelete

public int executeDelete(ModelExecutionContext context)
                  throws java.sql.SQLException,
                         ModelControlException
Description copied from interface: DeleteQueryModel
Executes the model in deleting mode, using the provided execution context
Specified by:
executeDelete in interface DeleteQueryModel
Following copied from interface: com.iplanet.jato.model.sql.DeleteQueryModel
Parameters:
context - The execution context to be used during the execution of this query. This parameter cannot be null or an java.lang.IllegalArgumentException will be thrown.
Returns:
The number of rows in the database affected by this query

getNumAffectedRows

public int getNumAffectedRows()
Returns the number of rows affected by the most recently executed query. This value will only be valid if the last executed query was a modifying query
Specified by:
getNumAffectedRows in interface ModifyingQueryModel
Returns:
The number of rows affected by the last modifying query, or -1

setNumAffectedRows

protected void setNumAffectedRows(int value)
Sets the number of rows affected by the most recently executed query. This method is used internally and should not be generally useful to developers.
Parameters:
value - The number of rows affected by the last modifying query, or -1