org.apache.myfaces.trinidad.model
Class CollectionModel

java.lang.Object
  extended by javax.faces.model.DataModel
      extended by org.apache.myfaces.trinidad.model.CollectionModel
All Implemented Interfaces:
Iterable, LocalRowKeyIndex, RowKeyIndex
Direct Known Subclasses:
CollectionModelDecorator, SortableModel, TreeModel

public abstract class CollectionModel
extends javax.faces.model.DataModel
implements RowKeyIndex, LocalRowKeyIndex

The data model that is used by the Trinidad Table and Iterator components. This extends the Faces DataModel class and adds on support for rowKeys and sorting. Ordinary DataModels are still supported, and will automatically be wrapped into CollectionModels, but without the added functionality.

Row key support

In the Faces DataModel, rows are identified entirely by index. This causes major problems if the underlying data changes from one request to the next - a user request to delete one row may delete a different row because a row got added by another user, etc. To work around this, CollectionModel is based around row keys instead of indices. An implementation of CollectionModel must implement getRowKey() and setRowKey(), and handle conversion from integer indices to row keys. A trivial implementation might simply use Integer objects as the row keys, but a better version could use a unique ID in the row.


Nested Class Summary
 
Nested classes/interfaces inherited from interface org.apache.myfaces.trinidad.model.LocalRowKeyIndex
LocalRowKeyIndex.Confidence, LocalRowKeyIndex.LocalCachingStrategy
 
Constructor Summary
CollectionModel()
           
 
Method Summary
 void addRowKeyChangeListener(RowKeyChangeListener listener)
           Adds the listener to the Set of RowKeyChangeListeners on the Collection.
 boolean areRowsAvailable(int rowsToCheck)
          Check if a range of rows is available starting from the current row.
 boolean areRowsAvailable(int startIndex, int rowsToCheck)
          Check if a range of rows is available from a starting index.
 boolean areRowsAvailable(Object startRowKey, int rowsToCheck)
          Check if a range of rows is available from a starting row key This method makes the row with the given row key current and calls #areRowsAvailable(rowsToCheck).
 boolean areRowsLocallyAvailable(int rowsToCheck)
          Check if a range of rows is locally available starting from current position.
 boolean areRowsLocallyAvailable(int startIndex, int rowsToCheck)
          Check if a range of rows is locally available starting from a row index.
 boolean areRowsLocallyAvailable(Object startRowKey, int rowsToCheck)
          Check if a range of rows is locally available starting from a row key.
 void clearCachedRow(int index)
          Clears the row with the given index from local cache.
 void clearCachedRow(Object rowKey)
          Clears the row with the given row key from local cache.
 void clearCachedRows(int startingIndex, int rowsToClear)
          Clears a range of rows from local cache starting from a row index.
 void clearCachedRows(Object startingRowKey, int rowsToClear)
          Clears a range of rows from local cache starting from a row key This is a do nothing implemenation.
 void clearLocalCache()
          Clears the local cache.
protected  void fireRowKeyChange(RowKeyChangeEvent event)
          Fire an existing RowKeyChangeEvent to any registered listeners.
 LocalRowKeyIndex.LocalCachingStrategy getCachingStrategy()
          Returns the row caching strategy used by this implemenation.
 int getEstimatedRowCount()
          Convenient API to return a row count estimate.
 LocalRowKeyIndex.Confidence getEstimatedRowCountConfidence()
          Helper API to determine if the row count returned from getEstimatedRowCount() is EXACT, or an ESTIMATE.
 Object getRowData(int rowIndex)
          Gets the rowData at the given index.
 Object getRowData(Object rowKey)
          Returns the rowData for the given rowKey without changing model currency.
abstract  Object getRowKey()
          Gets the rowKey of the current row.
 List<SortCriterion> getSortCriteria()
          Gets the criteria that this collection is sorted by.
 boolean isRowAvailable(int rowIndex)
          Checks to see if the row at the given index is available.
 boolean isRowAvailable(Object rowKey)
          Check for an available row by row key.
 boolean isRowLocallyAvailable(int rowIndex)
          Given a row index, check if the row is locally available.
 boolean isRowLocallyAvailable(Object rowKey)
          Given a row key, check if the row is locally available.
 boolean isSortable(String property)
          Return true if this collection is sortable by the given property.
 void removeRowKeyChangeListener(RowKeyChangeListener listener)
           Remove an existing listener from the Set of RowKeyChangeListeners on the Collection.
abstract  void setRowKey(Object key)
          Finds the row with the matching key and makes it current
 void setSortCriteria(List<SortCriterion> criteria)
          Sorts this collection by the given criteria.
 
Methods inherited from class javax.faces.model.DataModel
addDataModelListener, getDataModelListeners, getRowCount, getRowData, getRowIndex, getWrappedData, isRowAvailable, iterator, removeDataModelListener, setRowIndex, setWrappedData
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.myfaces.trinidad.model.RowKeyIndex
getRowCount, getRowData, getRowIndex, isRowAvailable, setRowIndex
 

Constructor Detail

CollectionModel

public CollectionModel()
Method Detail

getRowKey

public abstract Object getRowKey()
Gets the rowKey of the current row. rowKeys are safer to use than row indices because rowKeys are unaffected by mutations to this collection. rowKeys should have efficient implementations of Object.equals(java.lang.Object) and Object.hashCode() as they will be used as keys in hashtables. rowKeys should also be Serializable, so that the application can run under all JSF state-saving schemes.

Specified by:
getRowKey in interface RowKeyIndex
Returns:
this key should be Serializable and immutable.
See Also:
setRowKey(java.lang.Object)

setRowKey

public abstract void setRowKey(Object key)
Finds the row with the matching key and makes it current

Specified by:
setRowKey in interface RowKeyIndex
Parameters:
key - the rowKey, previously obtained from getRowKey().

isRowAvailable

public boolean isRowAvailable(int rowIndex)
Checks to see if the row at the given index is available. This method makes the given row current and calls DataModel.isRowAvailable(). Finally, the row that was current before this method was called is made current again.

Specified by:
isRowAvailable in interface RowKeyIndex
Parameters:
rowIndex - the index of the row to check.
Returns:
true if data for the row exists.
See Also:
DataModel.isRowAvailable()

isRowAvailable

public boolean isRowAvailable(Object rowKey)
Check for an available row by row key. This method makes the given row current and calls DataModel.isRowAvailable(). Finally, the row that was current before this method was called is made current again.

Specified by:
isRowAvailable in interface RowKeyIndex
Parameters:
rowKey - the row key for the row to check.
Returns:
true if data for the row exists otherwise return false
See Also:
DataModel.isRowAvailable()

getRowData

public Object getRowData(int rowIndex)
Gets the rowData at the given index. This method makes the given row current and calls DataModel.getRowData(). Finally, the row that was current before this method was called is made current again.

Specified by:
getRowData in interface RowKeyIndex
Parameters:
rowIndex - the index of the row to get data from.
Returns:
the data for the given row.
See Also:
DataModel.getRowData()

getRowData

public Object getRowData(Object rowKey)
Returns the rowData for the given rowKey without changing model currency. Implementations may choose to implement this behavior by saving and restoring the currency.

Specified by:
getRowData in interface RowKeyIndex
Parameters:
rowKey - the row key of the row to get data from.
Returns:
the data for the given row.
See Also:
DataModel.getRowData()

isSortable

public boolean isSortable(String property)
Return true if this collection is sortable by the given property. This implementation always returns false;


getSortCriteria

public List<SortCriterion> getSortCriteria()
Gets the criteria that this collection is sorted by. This method should never return null. This implementation always returns an empty List.

Returns:
each element in this List is of type SortCriterion. An empty list is returned if this collection is not sorted.
See Also:
SortCriterion

setSortCriteria

public void setSortCriteria(List<SortCriterion> criteria)
Sorts this collection by the given criteria.

Parameters:
criteria - Each element in this List must be of type SortCriterion. The empty list may be used to cancel any sort order. null should be treated the same as an empty list.
See Also:
SortCriterion

areRowsAvailable

public boolean areRowsAvailable(int startIndex,
                                int rowsToCheck)
Check if a range of rows is available from a starting index. The current row does not change after this call

Specified by:
areRowsAvailable in interface RowKeyIndex
Parameters:
startIndex - the starting index for the range
rowsToCheck - number of rows to check. If rowsToCheck < 0 set startIndex = startIndex - abs(rowsToCheck) + 1. This allows for checking for row availability from the end position. For example to check for availability of n rows from the end, call isRangeAvailable(getRowCount()-1, -n)
Returns:
true if rows are available otherwise return false

areRowsAvailable

public boolean areRowsAvailable(Object startRowKey,
                                int rowsToCheck)
Check if a range of rows is available from a starting row key This method makes the row with the given row key current and calls #areRowsAvailable(rowsToCheck). The current row does not change after this call

Specified by:
areRowsAvailable in interface RowKeyIndex
Parameters:
startRowKey - the starting row key for the range
rowsToCheck - number of rows to check
Returns:
true if rows are available otherwise return false
See Also:
areRowsAvailable(int).

areRowsAvailable

public boolean areRowsAvailable(int rowsToCheck)
Check if a range of rows is available starting from the current row. This implementation checks the start and end rows in the range for availability. If the number of requested rows is greater than the total row count, this implementation checks for available rows up to the row count. The current row does not change after this call

Specified by:
areRowsAvailable in interface RowKeyIndex
Parameters:
rowsToCheck - number of rows to check
Returns:
true rows are available otherwise return false

addRowKeyChangeListener

public void addRowKeyChangeListener(RowKeyChangeListener listener)

Adds the listener to the Set of RowKeyChangeListeners on the Collection.

The same listener instance may be added multiple times, but will only be called once per change.

Since the Collection may have a lifetime longer than Request, the listener implementation should take care not to maintain any references to objects only valid in the current Request. For example, if a UIComponent wishes to listen on a Collection, the UIComponent cannot use a listener that maintains a Java reference to the UIComponent instance because UIComponent instances are only valid for the current request (this also precludes the use of a non-static inner class for the listener). Instead, the UIComponent would need to use an indirect reference such as ComponentReference to dynamically find the correct instance to use. In the case where the Collection has a short lifetime, the code that adds the listener needs to ensure that it executes every time the Collection instance is reinstantiated.

Parameters:
listener - The listener for RowKeyChangeEvents to add to the Collection
See Also:
removeRowKeyChangeListener(org.apache.myfaces.trinidad.model.RowKeyChangeListener)

removeRowKeyChangeListener

public void removeRowKeyChangeListener(RowKeyChangeListener listener)

Remove an existing listener from the Set of RowKeyChangeListeners on the Collection.

The same listener instance may be removed multiple times wihtout failure.

Parameters:
listener - The listener for RowKeyChangeEvents to remove from the Collection

fireRowKeyChange

protected void fireRowKeyChange(RowKeyChangeEvent event)
Fire an existing RowKeyChangeEvent to any registered listeners. No event is fired if the given event's old and new row keys are equal and non-null.

Parameters:
event - The RowKeyChangeEvent object.

areRowsLocallyAvailable

public boolean areRowsLocallyAvailable(int startIndex,
                                       int rowsToCheck)
Check if a range of rows is locally available starting from a row index.

Specified by:
areRowsLocallyAvailable in interface LocalRowKeyIndex
Parameters:
startIndex - starting row index to check
rowsToCheck - number of rows to check
Returns:
default implementation returns false
See Also:
areRowsAvailable(int, int)

areRowsLocallyAvailable

public boolean areRowsLocallyAvailable(Object startRowKey,
                                       int rowsToCheck)
Check if a range of rows is locally available starting from a row key.

Specified by:
areRowsLocallyAvailable in interface LocalRowKeyIndex
Parameters:
startRowKey - starting row key to check
rowsToCheck - number of rows to check
Returns:
default implementation returns false
See Also:
areRowsAvailable(Object, int)

areRowsLocallyAvailable

public boolean areRowsLocallyAvailable(int rowsToCheck)
Check if a range of rows is locally available starting from current position. This implementation checks for a valid current index and delegates to areRowsLocallyAvailable(startIndex, rowsToCheck)

Specified by:
areRowsLocallyAvailable in interface LocalRowKeyIndex
Parameters:
rowsToCheck - number of rows to check
Returns:
default implementation returns false
See Also:
areRowsLocallyAvailable(startIndex, rowsToCheck)

isRowLocallyAvailable

public boolean isRowLocallyAvailable(int rowIndex)
Given a row index, check if the row is locally available.

Specified by:
isRowLocallyAvailable in interface LocalRowKeyIndex
Parameters:
rowIndex - row index to check
Returns:
default implementation returns false

isRowLocallyAvailable

public boolean isRowLocallyAvailable(Object rowKey)
Given a row key, check if the row is locally available.

Specified by:
isRowLocallyAvailable in interface LocalRowKeyIndex
Parameters:
rowKey - row key to check
Returns:
default implementation returns false

getEstimatedRowCount

public int getEstimatedRowCount()
Convenient API to return a row count estimate.

Specified by:
getEstimatedRowCount in interface LocalRowKeyIndex
Returns:
This implementation returns exact row count
See Also:
DataModel.getRowCount()

getEstimatedRowCountConfidence

public LocalRowKeyIndex.Confidence getEstimatedRowCountConfidence()
Helper API to determine if the row count returned from getEstimatedRowCount() is EXACT, or an ESTIMATE.

Specified by:
getEstimatedRowCountConfidence in interface LocalRowKeyIndex
Returns:
This implementation returns exact row count
See Also:
DataModel.getRowCount()

clearCachedRow

public void clearCachedRow(int index)
Clears the row with the given index from local cache. This is a do nothing implementaion.

Specified by:
clearCachedRow in interface LocalRowKeyIndex
Parameters:
index - row index for the row to remove from cache
See Also:
clearCachedRows(int, int)

clearCachedRow

public void clearCachedRow(Object rowKey)
Clears the row with the given row key from local cache. This is a do nothing implementaion which delegates to the correcsponding range based api

Specified by:
clearCachedRow in interface LocalRowKeyIndex
Parameters:
rowKey - row key for the row to remove from cache
See Also:
clearCachedRows(Object, int)

clearCachedRows

public void clearCachedRows(int startingIndex,
                            int rowsToClear)
Clears a range of rows from local cache starting from a row index. This is a do nothing implemenation.

Specified by:
clearCachedRows in interface LocalRowKeyIndex
Parameters:
startingIndex - starting row index to clear the local cache from
rowsToClear - number of rows to clear
See Also:
clearLocalCache()

clearCachedRows

public void clearCachedRows(Object startingRowKey,
                            int rowsToClear)
Clears a range of rows from local cache starting from a row key This is a do nothing implemenation.

Specified by:
clearCachedRows in interface LocalRowKeyIndex
Parameters:
startingRowKey - starting row key to clear the local cache from
rowsToClear - number of rows to clear
See Also:
clearLocalCache()

clearLocalCache

public void clearLocalCache()
Clears the local cache. This is a do nothing implementation

Specified by:
clearLocalCache in interface LocalRowKeyIndex

getCachingStrategy

public LocalRowKeyIndex.LocalCachingStrategy getCachingStrategy()
Returns the row caching strategy used by this implemenation. Default implementation indicates no caching supported

Specified by:
getCachingStrategy in interface LocalRowKeyIndex
Returns:
caching strategy none
See Also:
LocalRowKeyIndex.LocalCachingStrategy


Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.