org.apache.myfaces.trinidad.model

## Class CollectionModel

- java.lang.Object
- - javax.faces.model.DataModel
  - - 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`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `UNKNOWN_ROW_LIMIT`
    `static int` | `UNLIMITED_ROW`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CollectionModel()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `void` | `ensureRowsAvailable(int rowCount)` Ensure that the model has at least rowCount number of rows.
    `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.
    `int` | `getRowLimit()` Gets the row limit of this collection model.
    `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`

- - ### Field Detail

    - #### UNLIMITED_ROW

          public static final int UNLIMITED_ROW

      See Also:
        Constant Field Values

    - #### UNKNOWN_ROW_LIMIT

          public static final int UNKNOWN_ROW_LIMIT

      See Also:
        Constant Field Values

  - ### 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`

    - #### ensureRowsAvailable

          public void ensureRowsAvailable(int rowCount)

      Ensure that the model has at least rowCount number of rows. This is especially useful for collection model that support paging. The default implementation is a no-op.
      Parameters:
        `rowCount` - the number of rows the model should hold.

    - #### getRowLimit

          public int getRowLimit()

      Gets the row limit of this collection model. Default is to return UNKNOWN_ROW_LIMIT. Subclasses should override this method if row limit is enforced.
      Returns:
        the maximum number of rows this collection can hold, possible return values are: A positive number: the maximum number of rows the collection can hold UNKNOWN_ROW_LIMIT: row limit is unknown. UNLIMITED_ROW: there is no limit

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