javax.faces.model

## Class DataModel<E>

- java.lang.Object
- - javax.faces.model.DataModel<E>

- All Implemented Interfaces:
    Iterable<E>
  Direct Known Subclasses:
    ArrayDataModel, CollectionDataModel, ListDataModel, ResultDataModel, ResultSetDataModel, ScalarDataModel

      public abstract class DataModel<E>
      extends Object
      implements Iterable<E>

  DataModel is an abstraction around arbitrary data binding technologies that can be used to adapt a variety of data sources for use by JavaServer Faces components that support per-row processing for their child components (such as `UIData`.

  The data collection underlying a `DataModel` instance is modeled as a collection of row objects that can be accessed by a zero-relative cursor (row index). The APIs provide mechanisms to position to a specified zero-relative row index, and to retrieve an object that represents the data that corresponds to the current row index.

  A concrete `DataModel` instance is attached to a particular collection of underlying data by calling the `setWrappedData()` method. It can be detached from that underlying data collection by passing a `null` parameter to this method.

  Concrete `DataModel` implementations must provide a public zero-arguments constructor that calls `setWrappedData(null)`. A convenience constructor that takes a wrapped object of the appropriate type (and passes it on via a call to `setWrappedData()`, should also be provided.

  Event listeners may be registered to receive notifications of when a new row index is selected.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataModel()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDataModelListener(DataModelListener listener)` Add a new `DataModelListener` to the set interested in notifications from this `DataModel`.
    `DataModelListener[]` | `getDataModelListeners()` Return the set of `DataModelListener`s interested in notifications from this `DataModel`.
    `abstract int` | `getRowCount()` Return the number of rows of data objects represented by this `DataModel`.
    `abstract E` | `getRowData()` Return an object representing the data for the currenty selected row index.
    `abstract int` | `getRowIndex()` Return the zero-relative index of the currently selected row.
    `abstract Object` | `getWrappedData()` Return the object representing the data wrapped by this `DataModel`, if any.
    `abstract boolean` | `isRowAvailable()` Return a flag indicating whether there is `rowData` available at the current `rowIndex`.
    `Iterator<E>` | `iterator()` Return a read-only `Iterator` over the row data for this model.
    `void` | `removeDataModelListener(DataModelListener listener)` Remove an existing `DataModelListener` from the set interested in notifications from this `DataModel`.
    `abstract void` | `setRowIndex(int rowIndex)` Set the zero-relative index of the currently selected row, or -1 to indicate that we are not positioned on a row.
    `abstract void` | `setWrappedData(Object data)` Set the object representing the data collection wrapped by this `DataModel`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DataModel

          public DataModel()

  - ### Method Detail

    - #### isRowAvailable

          public abstract boolean isRowAvailable()

      Return a flag indicating whether there is `rowData` available at the current `rowIndex`. If no `wrappedData` is available, return `false`.

      Throws:
        `FacesException` - if an error occurs getting the row availability

    - #### getRowCount

          public abstract int getRowCount()

      Return the number of rows of data objects represented by this `DataModel`. If the number of rows is unknown, or no `wrappedData` is available, return -1.

      Throws:
        `FacesException` - if an error occurs getting the row count

    - #### getRowData

          public abstract E getRowData()

      Return an object representing the data for the currenty selected row index. If no `wrappedData` is available, return `null`.

      Throws:
        `FacesException` - if an error occurs getting the row data
        `IllegalArgumentException` - if now row data is available at the currently specified row index

    - #### getRowIndex

          public abstract int getRowIndex()

      Return the zero-relative index of the currently selected row. If we are not currently positioned on a row, or no `wrappedData` is available, return -1.

      Throws:
        `FacesException` - if an error occurs getting the row index

    - #### setRowIndex

          public abstract void setRowIndex(int rowIndex)

      Set the zero-relative index of the currently selected row, or -1 to indicate that we are not positioned on a row. It is possible to set the row index at a value for which the underlying data collection does not contain any row data. Therefore, callers may use the `isRowAvailable()` method to detect whether row data will be available for use by the `getRowData()` method.

      If there is no `wrappedData` available when this method is called, the specified `rowIndex` is stored (and may be retrieved by a subsequent call to `getRowData()`), but no event is sent. Otherwise, if the currently selected row index is changed by this call, a `DataModelEvent` will be sent to the `rowSelected()` method of all registered `DataModelListener`s.

      Parameters:
        `rowIndex` - The new zero-relative index (must be non-negative)
      Throws:
        `FacesException` - if an error occurs setting the row index
        `IllegalArgumentException` - if `rowIndex` is less than -1

    - #### getWrappedData

          public abstract Object getWrappedData()

      Return the object representing the data wrapped by this `DataModel`, if any.

    - #### setWrappedData

          public abstract void setWrappedData(Object data)

      Set the object representing the data collection wrapped by this `DataModel`. If the specified `data` is `null`, detach this `DataModel` from any previously wrapped data collection instead.

      If `data` is non-`null`, the currently selected row index must be set to zero, and a `DataModelEvent` must be sent to the `rowSelected()` method of all registered `DataModelListener`s indicating that this row is now selected.

      Parameters:
        `data` - Data collection to be wrapped, or `null` to detach from any previous data collection
      Throws:
        `ClassCastException` - if `data` is not of the appropriate type for this `DataModel` implementation

    - #### addDataModelListener

          public void addDataModelListener(DataModelListener listener)

      Add a new `DataModelListener` to the set interested in notifications from this `DataModel`.

      Parameters:
        `listener` - The new `DataModelListener` to be registered
      Throws:
        `NullPointerException` - if `listener` is `null`

    - #### getDataModelListeners

          public DataModelListener[] getDataModelListeners()

      Return the set of `DataModelListener`s interested in notifications from this `DataModel`. If there are no such listeners, an empty array is returned.

    - #### removeDataModelListener

          public void removeDataModelListener(DataModelListener listener)

      Remove an existing `DataModelListener` from the set interested in notifications from this `DataModel`.

      Parameters:
        `listener` - The old `DataModelListener` to be deregistered
      Throws:
        `NullPointerException` - if `listener` is `null`

    - #### iterator

          public Iterator<E> iterator()

      Return a read-only `Iterator` over the row data for this model.

      Specified by:
        `iterator` in interface `Iterable<E>`
      Since:
        2.0

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.