com.iplanet.jato.model.sql
Class ResultSetModelBase

java.lang.Object
  |
  +--com.iplanet.jato.model.DefaultModel
        |
        +--com.iplanet.jato.model.sql.ResultSetModelBase
All Implemented Interfaces:
ContextualModel, DatasetModel, Model, java.io.Serializable
Direct Known Subclasses:
QueryModelBase, StoredProcModelBase

public class ResultSetModelBase
extends DefaultModel

Model base class that provides significant functionality to cope with the vagaries of JDBC result sets as a model data stores. This primary value this class adds is in caching of result set data, thus providing bidirectional and repeatable access to that data. This implementation caches result set data for two reasons. First, basic JDBC drivers only provide unidirectional reading of result set data. Additionally, such drivers don't allow multiple reads of result set data. Both of these factors amount to significant difficulty when developing with vanilla JDBC. Second, the result set may not be available for the entire life of this model, but the data may be needed for the life of this model. This model attempts to be as efficient as possible in its operation, including in its implementation of data caching. By specifying detailed operation information via execution contexts, users of this model can specify exactly how they want data to be fetched and cached.

Version:
JATO/1.2.2 $Id: ResultSetModelBase.java,v 1.25 2002/03/16 03:26:33 todd Exp $
See Also:
Serialized Form

Inner classes inherited from class com.iplanet.jato.model.DefaultModel
DefaultModel.Context, DefaultModel.RowValueArrayList
 
Field Summary
protected static boolean DEBUG_NEXTROW
           
protected static boolean DEBUG_POS_RESULTSET
           
protected static boolean DEBUG_SYNCROW
           
protected static boolean DEBUG_UPDATE_MODEL
           
protected static boolean OPTION_COERCE_CACHED_RESULT_SET_VALUES
           
protected static boolean OPTION_COERCE_VALUE_TYPES
           
protected static int SYNCROW_ALREADY_SYNCHRONIZED
           
protected static int SYNCROW_FOUND_DATA
           
protected static int SYNCROW_NO_MORE_DATA
           
 
Fields inherited from class com.iplanet.jato.model.DefaultModel
DEFAULT_CONTEXT_NAME, UNDEFINED_ROW_INDEX
 
Constructor Summary
ResultSetModelBase()
          Default constructor
ResultSetModelBase(QueryFieldSchema schema)
          Create an instance with the specified field schema
 
Method Summary
 void beforeFirst()
          Moves the internal location iterator to a special position such that a call to next() will position the location at the first row (if available).
 void clear()
          Clears all values (from all rows) in this model
protected  void clearResultSet()
           
 boolean first()
          Moves the internal location iterator to the first available row.
 java.lang.Class getFieldClass(java.lang.String name)
           
 QueryFieldSchema getFieldSchema()
          Returns the field schema used to resolve logical field references to physical field references
 int getLocation()
          Returns the current row index
 int getLocationOffset()
          Returns the offset of the first row of data
 java.sql.ResultSet getResultSet()
          Returns the current result set
 int getSize()
          Depending on the circumstances under which this model was executed (as specified by the execution context), returns the number of rows of data available from the result set.
protected  java.util.Map getValueMap(int row)
          Returns the value map for the specified row.
 boolean hasMoreResults()
           
 boolean hasPreviousResults()
           
 boolean hasValue(java.lang.String name)
          Returns whether a value exists for the specified name
 boolean last()
          Moves the internal location iterator to the last available row.
 boolean next()
          Moves the internal location iterator to the next available row
protected  void positionResultSet(DatasetModelExecutionContext context)
          This method is only intended to be called after a SELECT query has been executed and the new result set has been cached.
protected  void positionResultSet(int offset, int numRows)
          This method is only intended to be called after a SELECT query has been executed and the new result set has been cached.
 boolean previous()
          Moves the internal location iterator to the previous available row
protected  void resolveResultSetColumnSet()
           
 void setFieldSchema(QueryFieldSchema value)
          Sets the field schema used to resolve logical field references to physical field references
 void setLocation(int location)
          Sets the current row index
protected  void setLocationOffset(int value)
           
protected  void setMoreResults(boolean value)
           
protected  void setPreviousResults(boolean value)
           
 void setResultSet(java.sql.ResultSet value)
          Sets the current result set
 void setSize(int value)
          Because this model uses a result set as a backing data store, this method cannot be used in this class.
 void setValue(java.lang.String name, java.lang.Object value)
          Sets a named value in this model.
 void setValues(java.lang.String name, java.lang.Object[] values)
          Sets a named set of values in this model
protected  int synchronizeRow(int row)
          This method copies data from the ResultSet to the model.
protected  void updateModel()
          Reads the data from the current result set row into the model's cache.
 
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
 

Field Detail

SYNCROW_NO_MORE_DATA

protected static final int SYNCROW_NO_MORE_DATA

SYNCROW_ALREADY_SYNCHRONIZED

protected static final int SYNCROW_ALREADY_SYNCHRONIZED

SYNCROW_FOUND_DATA

protected static final int SYNCROW_FOUND_DATA

OPTION_COERCE_VALUE_TYPES

protected static final boolean OPTION_COERCE_VALUE_TYPES

OPTION_COERCE_CACHED_RESULT_SET_VALUES

protected static final boolean OPTION_COERCE_CACHED_RESULT_SET_VALUES

DEBUG_UPDATE_MODEL

protected static final boolean DEBUG_UPDATE_MODEL

DEBUG_SYNCROW

protected static final boolean DEBUG_SYNCROW

DEBUG_NEXTROW

protected static final boolean DEBUG_NEXTROW

DEBUG_POS_RESULTSET

protected static final boolean DEBUG_POS_RESULTSET
Constructor Detail

ResultSetModelBase

public ResultSetModelBase()
Default constructor

ResultSetModelBase

public ResultSetModelBase(QueryFieldSchema schema)
Create an instance with the specified field schema
Method Detail

getResultSet

public java.sql.ResultSet getResultSet()
Returns the current result set

setResultSet

public void setResultSet(java.sql.ResultSet value)
Sets the current result set

resolveResultSetColumnSet

protected void resolveResultSetColumnSet()
                                  throws java.sql.SQLException

getFieldSchema

public QueryFieldSchema getFieldSchema()
Returns the field schema used to resolve logical field references to physical field references

setFieldSchema

public void setFieldSchema(QueryFieldSchema value)
Sets the field schema used to resolve logical field references to physical field references

getSize

public int getSize()
            throws ModelControlException
Depending on the circumstances under which this model was executed (as specified by the execution context), returns the number of rows of data available from the result set. However, there are some serious caveats to this seemingly simple functionality.

Very unfortunately, JDBC doesn't give us a way to determine the number of rows a query returned. Therefore, this method can only return the actual number of rows of data returned by a query if the entire result set is read and cached after execution. If a query is executed using the incremental fetch directive, the number of rows will not be available. In this case, this method simply returns -1.

Overrides:
getSize in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Returns:
The number of available rows
Throws:
ModelControlException - Thrown if an error occurrs determining the number of rows

setSize

public void setSize(int value)
             throws ModelControlException
Because this model uses a result set as a backing data store, this method cannot be used in this class. It throws a ModelControlException if called.
Overrides:
setSize in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Throws:
ModelControlException - Thrown if an error occurrs setting the number of rows

getLocation

public int getLocation()
                throws ModelControlException
Description copied from class: DefaultModel
Returns the current row index
Overrides:
getLocation in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Throws:
ModelControlException - Thrown if an error occurrs determining the current location

setLocation

public void setLocation(int location)
                 throws ModelControlException
Description copied from class: DefaultModel
Sets the current row index
Overrides:
setLocation in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Throws:
ModelControlException - Thrown if an error occurrs setting the current location

synchronizeRow

protected int synchronizeRow(int row)
                      throws java.sql.SQLException
This method copies data from the ResultSet to the model. This is necessary because certain JDBC drivers cannot support bi- directional iteration or reading a field's value more than once. Note that we lazily copy the result set's data to the model so that data should not be copied if it is not ever referenced.
Parameters:
row - The row number up to which to cache result set data

beforeFirst

public void beforeFirst()
                 throws ModelControlException
Description copied from class: DefaultModel
Moves the internal location iterator to a special position such that a call to next() will position the location at the first row (if available). Normally, a call to getLocation() after this method is called should return negative one (-1).
Overrides:
beforeFirst in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Throws:
ModelControlException - Thrown if an error occurrs setting the location to this special position

first

public boolean first()
              throws ModelControlException
Description copied from class: DefaultModel
Moves the internal location iterator to the first available row. Normally, a call to getLocation() after this method is called should return zero (0).
Overrides:
first in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Returns:
True if now positioned at a valid row, false if there is no available row
Throws:
ModelControlException - Thrown if an error occurrs moving to the first dataset

last

public boolean last()
             throws ModelControlException
Description copied from class: DefaultModel
Moves the internal location iterator to the last available row. Normally, a call to getLocation() after this method is called should return getSize()-1.
Overrides:
last in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Returns:
True if now positioned at a valid row, false if there is no available row
Throws:
ModelControlException - Thrown if an error occurrs moving to the last row

next

public boolean next()
             throws ModelControlException
Description copied from class: DefaultModel
Moves the internal location iterator to the next available row
Overrides:
next in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Returns:
True if now positioned at a valid row, false if there are no more rows
Throws:
ModelControlException - Thrown if an error occurrs positioning at the next row

previous

public boolean previous()
                 throws ModelControlException
Description copied from class: DefaultModel
Moves the internal location iterator to the previous available row
Overrides:
previous in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Returns:
True if now positioned at a valid row, false if there are no more rows
Throws:
ModelControlException - Thrown if an error occurrs positioning at the previous row

getFieldClass

public java.lang.Class getFieldClass(java.lang.String name)

hasValue

public boolean hasValue(java.lang.String name)
Description copied from class: DefaultModel
Returns whether a value exists for the specified name
Overrides:
hasValue in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Parameters:
The - name of the value to test
Returns:
True if the named value is present

setValue

public void setValue(java.lang.String name,
                     java.lang.Object value)
Description copied from class: DefaultModel
Sets a named value in this model. This method overwrites any current value or values. If multiple values were present previously, they are all discarded.
Overrides:
setValue in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Parameters:
name - The name of the value to set
value - The value to set in this model

setValues

public void setValues(java.lang.String name,
                      java.lang.Object[] values)
Description copied from class: DefaultModel
Sets a named set of values in this model
Overrides:
setValues in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Parameters:
name - The name of the value set to set in the model
values - The set of values to set in this model

clear

public void clear()
Description copied from class: DefaultModel
Clears all values (from all rows) in this model
Overrides:
clear in class DefaultModel

clearResultSet

protected void clearResultSet()

getLocationOffset

public int getLocationOffset()
Description copied from class: DefaultModel
Returns the offset of the first row of data
Overrides:
getLocationOffset in class DefaultModel
Following copied from class: com.iplanet.jato.model.DefaultModel
Returns:
This method always returns zero (0) in this implementation

setLocationOffset

protected void setLocationOffset(int value)

positionResultSet

protected void positionResultSet(DatasetModelExecutionContext context)
                          throws java.sql.SQLException
This method is only intended to be called after a SELECT query has been executed and the new result set has been cached.

positionResultSet

protected void positionResultSet(int offset,
                                 int numRows)
                          throws java.sql.SQLException
This method is only intended to be called after a SELECT query has been executed and the new result set has been cached.

hasPreviousResults

public boolean hasPreviousResults()
Returns:
true if there are additional results available before the beginning of the current dataset

setPreviousResults

protected void setPreviousResults(boolean value)

hasMoreResults

public boolean hasMoreResults()
Returns:
true if there are additional results available beyond the end of the current dataset

setMoreResults

protected void setMoreResults(boolean value)

getValueMap

protected java.util.Map getValueMap(int row)
Description copied from class: DefaultModel
Returns the value map for the specified row. If the model is in the "before first" state when this method is called, it automatically moves to the first (0th) row, creating it if necessary.
Overrides:
getValueMap in class DefaultModel

updateModel

protected void updateModel()
                    throws java.sql.SQLException
Reads the data from the current result set row into the model's cache.