com.iplanet.jato.model.sql
Interface SelectQueryModel

All Superinterfaces:
DatasetModel, ExecutingModel, Model, QueryModel, RetrievingDatasetModel, RetrievingModel, SQLModel
All Known Implementing Classes:
QueryModelBase

public interface SelectQueryModel
extends QueryModel, RetrievingDatasetModel

Specialization of QueryModel that supports SELECT SQL queries

Version:
JATO/1.2.2 $Id: SelectQueryModel.java,v 1.8 2002/03/16 03:26:33 todd Exp $

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.
 void clearFieldValueWhereCriteria()
          Removes all fields' request-scoped where clause criteria.
 void clearUserWhereCriteria()
          Removes all fields' session-scoped where clause criteria.
 java.sql.ResultSet executeSelect(DatasetModelExecutionContext context)
          Executes the model in retrieving/select mode, using the provided execution context
 java.sql.ResultSet getResultSet()
          Returns the last JDBC result set retrieved by this model.
 boolean hasUserWhereCriterion(java.lang.String logicalFieldName, java.lang.String operator, java.lang.Object value)
          Returns true if a criterion matching the provided specification already exists for this model.
 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 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.
 
Methods inherited from interface com.iplanet.jato.model.sql.QueryModel
getFieldSchema
 
Methods inherited from interface com.iplanet.jato.model.sql.SQLModel
getDataSourceName
 
Methods inherited from interface com.iplanet.jato.model.ExecutingModel
execute
 
Methods inherited from interface com.iplanet.jato.model.Model
getName, getValue, getValues, setName, setValue, setValues
 
Methods inherited from interface com.iplanet.jato.model.RetrievingModel
retrieve
 
Methods inherited from interface com.iplanet.jato.model.DatasetModel
beforeFirst, first, getLocation, getLocationOffset, getSize, last, next, previous, setLocation, setSize
 

Method Detail

executeSelect

public java.sql.ResultSet executeSelect(DatasetModelExecutionContext context)
                                 throws java.sql.SQLException,
                                        ModelControlException
Executes the model in retrieving/select mode, using the provided execution context
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.

getResultSet

public java.sql.ResultSet getResultSet()
Returns the last JDBC result set retrieved by this model. This method can generally be used to obtain direct access to the result set that underlies the target model. However, note that the execution context and the JDBC driver may alter the possible uses of this result set. For example, if the caller specifies at query execution a dataset offset greater than zero, the result may already be positioned at the beginning offset row; depending on the capability of the underlying JDBC driver, backward iteration through the result set may not be possible. Furthermore, some execution contexts may require that the model cache all data from the result set and close the result set returned by this method immediately. If this is the case, then the returned object may not be valid. Consult the documentation on execution contexts and your JDBC driver for more information.
Returns:
The last JDBC result set retrieved by this model, or null if no such result set exists. This method should return the same instance up until the model is executed again. This method should return null if the model executes an insert update, or delete operation.
See Also:
ModelExecutionContext

setFieldValueWhereCriterion

public void setFieldValueWhereCriterion(java.lang.String logicalFieldName)
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.

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)
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.

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)
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.

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()
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.

addUserWhereCriterion

public void addUserWhereCriterion(java.lang.String logicalFieldName,
                                  java.lang.Object value)
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.

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)
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.

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)
Returns true if a criterion matching the provided specification already exists for this model.

NOTE:
This implementation is currently quite inefficient when large numbers of user criteria are present. Avoid using if possible in such circumstances (this method may be used internally if the CHECK_FOR_EXISTING_USER_WHERE_CRITERIA flag is set to true).

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)
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.

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()
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.