New APIs for Trinidad CollectionModel and TreeModel to better deal with large data sets
----------------------------------------------------------------------------------------
Key: TRINIDAD-1620
URL: https://issues.apache.org/jira/browse/TRINIDAD-1620
Project: MyFaces Trinidad
Issue Type: New Feature
Components: Components
Affects Versions: 1.2.12-core
Environment: All
Reporter: Kamran Kashanian
Attachments: 1.2.12.2.patch, JDK5.1.2.12.2.patch
Submitting a proposal for a new set of APIs for Trinidad CollectionModel and
TreeModel. The new APIs are intended to enable a model user (usually the
renderer) to better deal with large data sets (large models) and provide the
user more control over API calls that can cause a potentially expensive data
fetch in the model.
The issue with the existing CollectionModel APIs is that APIs such as setRowKey/setRowIndex/isRowAvailable can force the model to perform a data fetch.
For large models, the renderer may need to optimize it's rendering and delay fetching data if a range of rows are not locally available. Also sometimes the client needs to convert row indices to a row keys (setRowIndex followed by getRowKey) without forcing a potentially expensive data fetch.
Proposing the following new APIs:
1) Add a new interface called LocalRowKeyIndex (modeled after the existing org.apache.myfaces.trinidad.model.RowKeyIndex interface) which provides a set of local APIs. The "local" APIs allow a client to query the model and determine if a set of rows are locally available. "Locally available" can mean the model has the given set of rows in a local cache and can honor a fetch request efficiently (for example, without performing a SQL query).
package org.apache.myfaces.trinidad.model;
public interface LocalRowKeyIndex
{
/**
* Given a row index, check if a row is locally available
* @param rowIndex index of row to check
* @return true if row is locally available
*/
public boolean isRowLocallyAvailable(int rowIndex);
/**
* Given a row key, check if a row is locally available
* @param rowKey row key for the row to check
* @return true if row is locally available
*/
public boolean isRowLocallyAvailable(Object rowKey);
/**
* Check if a range of rows is locally available starting from a row index
* @param startIndex staring index for the range
* @param rowCount number of rows in the range
* @return true if range of rows is locally available
*/
public boolean isRangeLocallyAvailable(int startIndex, int rowCount);
/**
* Check if a range of rows is locally available starting from a row key
* @param rowKey staring row key for the range
* @param rowCount number of rows in the range
* @return true if range of rows is locally available
*/
public boolean isRangeLocallyAvailable(Object rowKey, int rowCount);
/**
* Convenient API to return a row count estimate. This method can be optimized
* to avoid a data fetch which may be required to return an exact row count
* @return estimated row count
*/
public int getEstimatedRowCount();
/**
* Helper API to determine if the row count returned from {...@link #getEstimatedRowCount}
* is EXACT, or an ESTIMATE
*/
public Confidence getEstimatedRowCountConfidence();
/**
* Enum used in the {...@link #getEstimatedRowCountConfidence} API to determine
* if the row count is exact or an estimate
*/
public enum Confidence
{
/**
* The row count returned by {...@link #getEstimatedRowCount} is exact
*/
EXACT,
/**
* The row count returned by {...@link #getEstimatedRowCount} is an estimate
*/
ESTIMATE
}
}
2) Enhance the APIs in the existing
org.apache.myfaces.trinidad.model.RowKeyIndex interface to add support for:
a) Row key - based APIs so the client does not have to perform row key to row
index conversion (and potentially cause unnecessary data fetch)
b) Provide new APIs to enable the client to check for availability of a range
of rows without having to loop over the rows and call the existing
isRowAvailable API.
Add the following methods to the existing
org.apache.myfaces.trinidad.model.RowKeyIndex interface:
/**
* Check for an available row by row key.
* @param rowKey the row key for the row to check.
* @return true if a value exists; false otherwise.
*/
public boolean isRowAvailable(Object rowKey);
/**
* Get row data by row key.
* @param rowKey the row key for the row to get data.
* @return row data
*/
public Object getRowData(Object rowKey);
/**
* Check if a range of rows is available starting from the current position
* @param rowCount number of rows to check
* @return true if all rows in range are available
*/
public boolean isRangeAvailable(int rowCount);
/**
* Check if a range of rows is available from a starting index without
* requiring the client to iterate over the rows
* @param startIndex the starting index for the range
* @param rowCount number of rows to check
* @return true if all rows in range are available
*/
public boolean isRangeAvailable(int startIndex, int rowCount) ;
/**
* Check if a range of rows is available from a starting row key without
* requiring the client to iterate over the rows
* @param rowKey the starting row key for the range
* @param rowCount number of rows to check
* @return true if all rows in range are available
*/
public boolean isRangeAvailable(Object rowKey, int rowCount) ;
3) Provide local APIs in org.apache.myfaces.trinidad.model.TreeModel for example to check if data for a child collection is locally available:
/**
* Indicates whether data for a child model (children of the current node) is
* locally available. Locally available means no data fetch is required
* as a result of a call to {...@link #enterContainer}. The default
* implementation returns true if the current node is a container.
* Override to optimize for the case where child data is not locally available
* @return true if child data is locally available
*/
public boolean isChildCollectionLocallyAvailable()
{
return isContainer();
}
/**
* Indicates whether child data for the node with the given index is
* locally available. This method first checks to see if the parent node
* at the given index is locally available by calling {...@link
#isRowLocallyAvailable(int}.
* If the parent node is locally available, this method moves the model to the
* parent node and calls {...@link #isChildCollectionLocallyAvailable()}
* The current row does not change after this call
* @param index
* @return true if child data is available, false otherwise
*/
public boolean isChildCollectionLocallyAvailable(int index)
{
if (isRowLocallyAvailable(index))
{
int oldIndex = getRowIndex();
try
{
setRowIndex(index);
return isChildCollectionLocallyAvailable();
}
finally
{
setRowIndex(oldIndex);
}
}
else
{
return false;
}
}
/**
* Indicates whether child data for the node with the given row key is
* locally available. This method first checks to see if the parent node
* with the given row key is locally available by calling {...@link
#isRowLocallyAvailable(Object)}.
* If the parent node is locally available, this method moves the model to the
* parent node and calls {...@link #isChildCollectionLocallyAvailable()}
* The current row does not change after this call
* @param rowKey
* @return true if child data is available, false otherwise
*/
public boolean isChildCollectionLocallyAvailable(Object rowKey)
{
if (isRowLocallyAvailable(rowKey))
{
Object oldKey = getRowKey();
try
{
setRowKey(rowKey);
return isChildCollectionLocallyAvailable();
}
finally
{
setRowKey(oldKey);
}
}
else
{
return false;
}
}
The following changes will be required to support the above APIs:
1) Add the new LocalRowKeyIndex interface to the
org.apache.myfaces.trinidad.model. package
2) org.apache.myfaces.trinidad.model.CollectionModel will implement the new
LocalRowKeyIndex interface and will provide default implementation for the
local APIs. The default implementation of local APIs will just call the
existing non-local APIs
3) UIXIterator and UIXHierarchy will implement the new LocalRowKeyIndex
interface and provide the component level implementations for the local APIs.
The component level implementations just delegate to the model
4) Provide trivial implementation for the new APIs in
org.apache.myfaces.trinidad.model.CollectionModelDecorator
