DataModel (Java EE 5)

DataModel 是对任意数据绑定技术的抽象，这些技术可以用来适配很多数据源，以供支持子组件按行处理的 JavaServer Faces 组件（如 UIData）使用。

DataModel 实例的底层数据集合建模为行对象 Collection，这些对象可以通过以 0 开始的指针（行索引）进行访问。API 提供了一些机制用于定位到指定的以 0 开始的行索引，并获取代表当前行索引所对应数据的对象。

通过调用 setWrappedData() 方法可以将具体的 DataModel 实例连接到特定的底层数据 Collection。通过向此方法传递 null 参数可以使其脱离底层数据 Collection。

具体的 DataModel 实现必须提供一个公有的无参构造方法，该方法调用 setWrappedData(null)。还应提供一个便捷的构造方法，该方法接收适当类型的包装对象（并通过调用 setWrappedData() 传递该对象）。

可能要注册事件侦听器，以便在选定新的行索引时收到通知。

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.

public DataModel()

英文文档：

DataModel

public DataModel()

abstract public boolean isRowAvailable()

返回一个指示当前 rowIndex 是否有可用的 rowData 的标志。如果没有任何 wrappedData 可用，则返回 false。

Throws

FacesException: 如果检测行可用性时发生错误

英文文档：

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

abstract public int getRowCount()

返回此 DataModel 所表示的数据对象的行数。如果行数未知，或者没有任何可用的 wrappedData，则返回 -1。

Throws

FacesException: 如果获取行数时发生错误

英文文档：

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

abstract public Object getRowData()

返回表示当前选定行索引处相应数据的对象。如果没有任何可用的 wrappedData，则返回 null。

Throws	FacesException: 如果获取行数据时发生错误
Throws	IllegalArgumentException: 如果当前指定行索引处的行数据目前可用

英文文档：

getRowData

public abstract Object 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

abstract public int getRowIndex()

返回当前选定行索引（以 0 开始）。如果当前没有定位到某行，或没有任何可用的 wrappedData，则返回 -1。

Throws

FacesException: 如果获取行索引时发生错误

英文文档：

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

abstract public void setRowIndex(int rowIndex)

设置当前选定行的索引（以 0 开始）；或者 -1，表示没有定位到某行。可以将行索引设置为某个值，在该索引处底层数据 Collection 不包含任何行数据。因此，调用者可以使用 isRowAvailable() 方法检测是否可以通过 getRowData() 方法获得行数据。

如果调用此方法时没有任何可用的 wrappedData，则存储指定的 rowIndex（随后可以通过调用 getRowData() 获取），但是不发送任何事件。否则，如果此调用更改了当前选定的行索引，就会向所有已注册 DataModelListener 的 rowSelected() 方法发送 DataModelEvent。

rowIndex	新的以 0 开始的索引（必须为非负数）
Throws	FacesException: 如果设置行索引时发生错误
Throws	IllegalArgumentException: 如果 rowIndex 小于 -1

英文文档：

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 DataModelListeners.

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

abstract public Object getWrappedData()

返回表示此 DataModel 所包装数据的对象（如果有）。

英文文档：

getWrappedData

public abstract Object getWrappedData()

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

abstract public void setWrappedData(Object data)

设置表示此 DataModel 所包装数据 Collection 的对象。如果指定的 data 为 null，则改为使此 DataModel 脱离以前包装的任何数据 Collection。

如果 data 非 null，则当前选定的行索引必须设置为 0，并且必须向所有已注册 DataModelListener 的 rowSelected() 方法发送 DataModelEvent，以指示现在选定了此行。

data	要包装的数据 Collection；或者 null，表示脱离以前的任何数据 Collection
Throws	ClassCastException: 如果 data 的类型不适合此 DataModel 实现

英文文档：

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 DataModelListeners 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

public void addDataModelListener(DataModelListener listener)

向希望从此 DataModel 获得通知的集合添加一个新的 DataModelListener。

listener	要注册的新的 DataModelListener
Throws	NullPointerException: 如果 listener 为 null

英文文档：

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

public DataModelListener[] getDataModelListeners()

返回希望从此 DataModel 获得通知的 DataModelListener 集。如果不存在此类侦听器，则返回一个空数组。

英文文档：

getDataModelListeners

public DataModelListener[] getDataModelListeners()

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

public void removeDataModelListener(DataModelListener listener)

从希望从 DataModel 获得通知的集合中移除一个现有的 DataModelListener。

listener	要取消注册的旧 DataModelListener
Throws	NullPointerException: 如果 listener 为 null

英文文档：

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

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.