UIData (Java EE 5 SDK) - Java Platform, Enterprise Edition v5.0 API Specifications

Overview

Package

Class

Tree

Deprecated

Index

Help

Java EE 5 SDK

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.faces.component
Class UIData

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          javax.faces.component.UIData

All Implemented Interfaces:: NamingContainer, StateHolder

Direct Known Subclasses:: HtmlDataTable

public class UIData
extends UIComponentBase
implements NamingContainer
extends UIComponentBase
implements NamingContainer

UIData is a UIComponent that supports data binding to a collection of data objects represented by a DataModel instance, which is the current value of this component itself (typically established via a ValueExpression). During iterative processing over the rows of data in the data model, the object for the current row is exposed as a request attribute under the key specified by the var property.

Only children of type UIColumn should be processed by renderers associated with this component.

By default, the rendererType property is set to javax.faces.Table. This value can be changed by calling the setRendererType() method.

Field Summary

static String COMPONENT_FAMILY
          The standard component family for this component.

static String COMPONENT_TYPE
          The standard component type for this component.

Fields inherited from class javax.faces.component.UIComponent

bindings

Fields inherited from interface javax.faces.component.NamingContainer

SEPARATOR_CHAR

Constructor Summary

UIData()
          Create a new UIData instance with default property values.

Method Summary

void broadcast(FacesEvent event)
          Override the default UIComponentBase.broadcast(javax.faces.event.FacesEvent) processing to unwrap any wrapped FacesEvent and reset the current row index, before the event is actually broadcast.

void encodeBegin(FacesContext context)
          In addition to the default behavior, ensure that any saved per-row state for our child input components is discarded unless it is needed to rerender the current page with errors.

String getClientId(FacesContext context)
          Return a client identifier for this component that includes the current value of the rowIndex property, if it is not set to -1.

protected DataModel getDataModel()
          Return the internal DataModel object representing the data objects that we will iterate over in this component's rendering.

String getFamily()
          Return the identifier of the component family to which this component belongs.

int getFirst()
          Return the zero-relative row number of the first row to be displayed.

UIComponent getFooter()
          Return the footer facet of this component (if any).

UIComponent getHeader()
          Return the header facet of this component (if any).

int getRowCount()
          Return the number of rows in the underlying data model.

Object getRowData()
          Return the data object representing the data for the currently selected row index, if any.

int getRowIndex()
          Return the zero-relative index of the currently selected row.

int getRows()
          Return the number of rows to be displayed, or zero for all remaining rows in the table.

Object getValue()
          Return the value of the UIData.

String getVar()
          Return the request-scope attribute under which the data object for the current row will be exposed when iterating.

boolean invokeOnComponent(FacesContext context, String clientId, ContextCallback callback)
          Override behavior from UIComponentBase.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback) to provide special care for positioning the data properly before finding the component and invoking the callback on it.

boolean isRowAvailable()
          Return a flag indicating whether there is rowData available at the current rowIndex.

void processDecodes(FacesContext context)
          Override the default UIComponentBase.processDecodes(javax.faces.context.FacesContext) processing to perform the following steps.

void processUpdates(FacesContext context)
          Override the default UIComponentBase.processUpdates(javax.faces.context.FacesContext) processing to perform the following steps.

void processValidators(FacesContext context)
          Override the default UIComponentBase.processValidators(javax.faces.context.FacesContext) processing to perform the following steps.

void queueEvent(FacesEvent event)
          Override the default UIComponentBase.queueEvent(javax.faces.event.FacesEvent) processing to wrap any queued events in a wrapper so that we can reset the current row index in broadcast().

void restoreState(FacesContext context, Object state)
           Perform any processing required to restore the state from the entries in the state Object.

Object saveState(FacesContext context)
           Gets the state of the instance as a Serializable Object.

protected void setDataModel(DataModel dataModel)
          Set the internal DataModel.

void setFirst(int first)
          Set the zero-relative row number of the first row to be displayed.

void setFooter(UIComponent footer)
          Set the footer facet of this component.

void setHeader(UIComponent header)
          Set the header facet of this component.

void setRowIndex(int rowIndex)
          Set the zero relative index of the current row, or -1 to indicate that no row is currently selected, by implementing the following algorithm.

void setRows(int rows)
          Set the number of rows to be displayed, or zero for all remaining rows in the table.

void setValue(Object value)
          Set the value of the UIData.

void setValueBinding(String name, ValueBinding binding)
          Deprecated. This has been replaced by setValueExpression(java.lang.String, javax.el.ValueExpression).

void setValueExpression(String name, ValueExpression binding)
          Set the ValueExpression used to calculate the value for the specified attribute or property name, if any.

void setVar(String var)
          Set the request-scope attribute under which the data object for the current row wil be exposed when iterating.

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, decode, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, getValueExpression, isRendered, isTransient, processRestoreState, processSaveState, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getContainerClientId

Methods inherited from class java.lang.Object

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

Field Summary
`static String`	`COMPONENT_FAMILY` The standard component family for this component.
`static String`	`COMPONENT_TYPE` The standard component type for this component.

Fields inherited from class javax.faces.component.UIComponent
`bindings`

Fields inherited from interface javax.faces.component.NamingContainer
`SEPARATOR_CHAR`

Constructor Summary
`UIData()` Create a new `UIData` instance with default property values.

Method Summary
`void`	`broadcast(FacesEvent event)` Override the default `UIComponentBase.broadcast(javax.faces.event.FacesEvent)` processing to unwrap any wrapped `FacesEvent` and reset the current row index, before the event is actually broadcast.
`void`	`encodeBegin(FacesContext context)` In addition to the default behavior, ensure that any saved per-row state for our child input components is discarded unless it is needed to rerender the current page with errors.
`String`	`getClientId(FacesContext context)` Return a client identifier for this component that includes the current value of the `rowIndex` property, if it is not set to -1.
`protected DataModel`	`getDataModel()` Return the internal `DataModel` object representing the data objects that we will iterate over in this component's rendering.
`String`	`getFamily()` Return the identifier of the component family to which this component belongs.
`int`	`getFirst()` Return the zero-relative row number of the first row to be displayed.
`UIComponent`	`getFooter()` Return the footer facet of this component (if any).
`UIComponent`	`getHeader()` Return the header facet of this component (if any).
`int`	`getRowCount()` Return the number of rows in the underlying data model.
`Object`	`getRowData()` Return the data object representing the data for the currently selected row index, if any.
`int`	`getRowIndex()` Return the zero-relative index of the currently selected row.
`int`	`getRows()` Return the number of rows to be displayed, or zero for all remaining rows in the table.
`Object`	`getValue()` Return the value of the UIData.
`String`	`getVar()` Return the request-scope attribute under which the data object for the current row will be exposed when iterating.
`boolean`	`invokeOnComponent(FacesContext context, String clientId, ContextCallback callback)` Override behavior from `UIComponentBase.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback)` to provide special care for positioning the data properly before finding the component and invoking the callback on it.
`boolean`	`isRowAvailable()` Return a flag indicating whether there is `rowData` available at the current `rowIndex`.
`void`	`processDecodes(FacesContext context)` Override the default `UIComponentBase.processDecodes(javax.faces.context.FacesContext)` processing to perform the following steps.
`void`	`processUpdates(FacesContext context)` Override the default `UIComponentBase.processUpdates(javax.faces.context.FacesContext)` processing to perform the following steps.
`void`	`processValidators(FacesContext context)` Override the default `UIComponentBase.processValidators(javax.faces.context.FacesContext)` processing to perform the following steps.
`void`	`queueEvent(FacesEvent event)` Override the default `UIComponentBase.queueEvent(javax.faces.event.FacesEvent)` processing to wrap any queued events in a wrapper so that we can reset the current row index in `broadcast()`.
`void`	`restoreState(FacesContext context, Object state)` Perform any processing required to restore the state from the entries in the state Object.
`Object`	`saveState(FacesContext context)` Gets the state of the instance as a `Serializable` Object.
`protected void`	`setDataModel(DataModel dataModel)` Set the internal DataModel.
`void`	`setFirst(int first)` Set the zero-relative row number of the first row to be displayed.
`void`	`setFooter(UIComponent footer)` Set the footer facet of this component.
`void`	`setHeader(UIComponent header)` Set the header facet of this component.
`void`	`setRowIndex(int rowIndex)` Set the zero relative index of the current row, or -1 to indicate that no row is currently selected, by implementing the following algorithm.
`void`	`setRows(int rows)` Set the number of rows to be displayed, or zero for all remaining rows in the table.
`void`	`setValue(Object value)` Set the value of the `UIData`.
`void`	`setValueBinding(String name, ValueBinding binding)` Deprecated. This has been replaced by `setValueExpression(java.lang.String, javax.el.ValueExpression)`.
`void`	`setValueExpression(String name, ValueExpression binding)` Set the `ValueExpression` used to calculate the value for the specified attribute or property name, if any.
`void`	`setVar(String var)` Set the request-scope attribute under which the data object for the current row wil be exposed when iterating.

Methods inherited from class javax.faces.component.UIComponentBase
`addFacesListener, decode, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, getValueExpression, isRendered, isTransient, processRestoreState, processSaveState, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient`

Methods inherited from class javax.faces.component.UIComponent
`encodeAll, getContainerClientId`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type for this component.

See Also:: Constant Field Values

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

The standard component family for this component.

See Also:: Constant Field Values

Constructor Detail

UIData

public UIData()

Create a new UIData instance with default property values.

Method Detail

getFamily

public String getFamily()

Description copied from class: UIComponent

Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the rendererType property, may be used to select the appropriate Renderer for this component instance.

Specified by:: getFamily in class UIComponent

getFirst

public int getFirst()

Return the zero-relative row number of the first row to be displayed.

setFirst

public void setFirst(int first)

Set the zero-relative row number of the first row to be displayed.

Parameters:: first - New first row number
Throws:: IllegalArgumentException - if first is negative

getFooter

public UIComponent getFooter()

Return the footer facet of this component (if any). A convenience method for getFacet("footer").

setFooter

public void setFooter(UIComponent footer)

Set the footer facet of this component. A convenience method for getFacets().put("footer", footer).

Parameters:: footer - the new footer facet
Throws:: NullPointerException - if footer is null

getHeader

public UIComponent getHeader()

Return the header facet of this component (if any). A convenience method for getFacet("header").

setHeader

public void setHeader(UIComponent header)

Set the header facet of this component. A convenience method for getFacets().put("header", header).

Parameters:: header - the new header facet
Throws:: NullPointerException - if header is null

isRowAvailable

public 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 int getRowCount()

Return the number of rows in the underlying data model. If the number of available rows is unknown, return -1.

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

getRowData

public Object getRowData()

Return the data object representing the data for the currently selected row index, if any.

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 int getRowIndex()

Return the zero-relative index of the currently selected row. If we are not currently positioned on a row, return -1. This property is not enabled for value binding expressions.

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

setRowIndex

public void setRowIndex(int rowIndex)

Set the zero relative index of the current row, or -1 to indicate that no row is currently selected, by implementing the following algorithm. 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.

Save current state information for all descendant components (as described below).
Store the new row index, and pass it on to the DataModel associated with this UIData instance.
If the new rowIndex value is -1:
- If the var property is not null, remove the corresponding request scope attribute (if any).
- Reset the state information for all descendant components (as described below).
If the new rowIndex value is not -1:
- If the var property is not null, call getRowData() and expose the resulting data object as a request scope attribute whose key is the var property value.
- Reset the state information for all descendant components (as described below).

To save current state information for all descendant components, UIData must maintain per-row information for each descendant as follows:

If the descendant is an instance of EditableValueHolder, save the state of its localValue property.
If the descendant is an instance of EditableValueHolder, save the state of the localValueSet property.
If the descendant is an instance of EditableValueHolder, save the state of the valid property.
If the descendant is an instance of EditableValueHolder, save the state of the submittedValue property.

To restore current state information for all descendant components, UIData must reference its previously stored information for the current rowIndex and call setters for each descendant as follows:

If the descendant is an instance of EditableValueHolder, restore the value property.
If the descendant is an instance of EditableValueHolder, restore the state of the localValueSet property.
If the descendant is an instance of EditableValueHolder, restore the state of the valid property.
If the descendant is an instance of EditableValueHolder, restore the state of the submittedValue property.

Parameters:: rowIndex - The new row index value, or -1 for no associated row
Throws:: FacesException - if an error occurs setting the row index; IllegalArgumentException - if rowIndex is less than -1

getRows

public int getRows()

Return the number of rows to be displayed, or zero for all remaining rows in the table. The default value of this property is zero.

setRows

public void setRows(int rows)

Set the number of rows to be displayed, or zero for all remaining rows in the table.

Parameters:: rows - New number of rows
Throws:: IllegalArgumentException - if rows is negative

getVar

public String getVar()

Return the request-scope attribute under which the data object for the current row will be exposed when iterating. This property is not enabled for value binding expressions.

setVar

public void setVar(String var)

Set the request-scope attribute under which the data object for the current row wil be exposed when iterating.

Parameters:: var - The new request-scope attribute name

saveState

public Object saveState(FacesContext context)

Description copied from interface: StateHolder

Gets the state of the instance as a Serializable Object.

If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(javax.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager

This method must not alter the state of the implementing object. In other words, after executing this code:

 Object state = component.saveState(facesContext);

component should be the same as before executing it.

The return from this method must be Serializable

Specified by:: saveState in interface StateHolder
Overrides:: saveState in class UIComponentBase

restoreState

public void restoreState(FacesContext context,
                         Object state)

Description copied from interface: StateHolder

Perform any processing required to restore the state from the entries in the state Object.

If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object) method on all those instances as well.

Specified by:: restoreState in interface StateHolder
Overrides:: restoreState in class UIComponentBase

getValue

public Object getValue()

Return the value of the UIData. This value must either be be of type DataModel, or a type that can be adapted into a DataModel. UIData will automatically adapt the following types:

Arrays
java.util.List
java.sql.ResultSet
javax.servlet.jsp.jstl.sql.Result

All other types will be adapted using the ScalarDataModel class, which will treat the object as a single row of data.

setValue

public void setValue(Object value)

Set the value of the UIData. This value must either be be of type DataModel, or a type that can be adapted into a DataModel.

Parameters:: value - the new value

setValueBinding

public void setValueBinding(String name,
                            ValueBinding binding)

Deprecated. This has been replaced by setValueExpression(java.lang.String, javax.el.ValueExpression).

If "name" is something other than "value", "var", or "rowIndex", rely on the superclass conversion from ValueBinding to ValueExpression.

Overrides:: setValueBinding in class UIComponentBase

Parameters:: name - Name of the attribute or property for which to set a ValueBinding; binding - The ValueBinding to set, or null to remove any currently set ValueBinding
Throws:: IllegalArgumentException - if name is one of id, parent, var, or rowIndex; NullPointerException - if name is null

setValueExpression

public void setValueExpression(String name,
                               ValueExpression binding)

Set the ValueExpression used to calculate the value for the specified attribute or property name, if any. In addition, if a ValueExpression is set for the value property, remove any synthesized DataModel for the data previously bound to this component.

Overrides:: setValueExpression in class UIComponentBase

Parameters:: name - Name of the attribute or property for which to set a ValueExpression; binding - The ValueExpression to set, or null to remove any currently set ValueExpression
Throws:: IllegalArgumentException - if name is one of id, parent, var, or rowIndex; NullPointerException - if name is null
Since:: 1.2

getClientId

public String getClientId(FacesContext context)

Return a client identifier for this component that includes the current value of the rowIndex property, if it is not set to -1. This implies that multiple calls to getClientId() may return different results, but ensures that child components can themselves generate row-specific client identifiers (since UIData is a NamingContainer).

Overrides:: getClientId in class UIComponentBase

Parameters:: context - The FacesContext for the current request
Throws:: NullPointerException - if context is null

invokeOnComponent

public boolean invokeOnComponent(FacesContext context,
                                 String clientId,
                                 ContextCallback callback)
                          throws FacesException

Override behavior from UIComponentBase.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback) to provide special care for positioning the data properly before finding the component and invoking the callback on it. If the argument clientId is equal to this.getClientId() simply invoke the contextCallback, passing the context argument and this as arguments, and return true. Otherwise, attempt to extract a rowIndex from the clientId. For example, if the argument clientId was form:data:3:customerHeader the rowIndex would be 3. Let this value be called newIndex. The current rowIndex of this instance must be saved aside and restored before returning in all cases, regardless of the outcome of the search or if any exceptions are thrown in the process.

The implementation of this method must never return true if setting the rowIndex of this instance to be equal to newIndex causes this instance to return false from isRowAvailable().

Overrides:: invokeOnComponent in class UIComponentBase

Parameters:: context - the FacesContext for the current request; clientId - the client identifier of the component to be passed to the argument callback.; callback - an implementation of the Callback interface.
Returns:: true if the a component with the given clientId is found, the callback method was successfully invoked passing that component as an argument, and no Exception was thrown. Returns false if no component with the given clientId is found.
Throws:: NullPointerException - if any of the arguments are null; FacesException - if the argument Callback throws an Exception, it is wrapped in a FacesException and re-thrown. Also throws FacesException if any exception is thrown when deriving the rowIndex from the argument clientId.
Since:: 1.2

queueEvent

public void queueEvent(FacesEvent event)

Override the default UIComponentBase.queueEvent(javax.faces.event.FacesEvent) processing to wrap any queued events in a wrapper so that we can reset the current row index in broadcast().

Overrides:: queueEvent in class UIComponentBase

Parameters:: event - FacesEvent to be queued
Throws:: IllegalStateException - if this component is not a descendant of a UIViewRoot; NullPointerException - if event is null

broadcast

public void broadcast(FacesEvent event)
               throws AbortProcessingException

Override the default UIComponentBase.broadcast(javax.faces.event.FacesEvent) processing to unwrap any wrapped FacesEvent and reset the current row index, before the event is actually broadcast. For events that we did not wrap (in queueEvent()), default processing will occur.

Overrides:: broadcast in class UIComponentBase

Parameters:: event - The FacesEvent to be broadcast
Throws:: AbortProcessingException - Signal the JavaServer Faces implementation that no further processing on the current event should be performed; IllegalArgumentException - if the implementation class of this FacesEvent is not supported by this component; NullPointerException - if event is null

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException

In addition to the default behavior, ensure that any saved per-row state for our child input components is discarded unless it is needed to rerender the current page with errors.

Overrides:: encodeBegin in class UIComponentBase

Parameters:: context - FacesContext for the current request
Throws:: IOException - if an input/output error occurs while rendering; NullPointerException - if context is null

processDecodes

public void processDecodes(FacesContext context)

Override the default UIComponentBase.processDecodes(javax.faces.context.FacesContext) processing to perform the following steps.

If the rendered property of this UIComponent is false, skip further processing.
Set the current rowIndex to -1.
Call the processDecodes() method of all facets of this UIData, in the order determined by a call to getFacets().keySet().iterator().
Call the processDecodes() method of all facets of the UIColumn children of this UIData.
Iterate over the set of rows that were included when this component was rendered (i.e. those defined by the first and rows properties), performing the following processing for each row:
- Set the current rowIndex to the appropriate value for this row.
- If isRowAvailable() returns true, iterate over the children components of each UIColumn child of this UIData component, calling the processDecodes() method for each such child.
Set the current rowIndex to -1.
Call the decode() method of this component.
If a RuntimeException is thrown during decode processing, call FacesContext.renderResponse() and re-throw the exception.

Overrides:: processDecodes in class UIComponentBase

Parameters:: context - FacesContext for the current request
Throws:: NullPointerException - if context is null

processValidators

public void processValidators(FacesContext context)

Override the default UIComponentBase.processValidators(javax.faces.context.FacesContext) processing to perform the following steps.

If the rendered property of this UIComponent is false, skip further processing.
Set the current rowIndex to -1.
Call the processValidators() method of all facets of this UIData, in the order determined by a call to getFacets().keySet().iterator().
Call the processValidators() method of all facets of the UIColumn children of this UIData.
Iterate over the set of rows that were included when this component was rendered (i.e. those defined by the first and rows properties), performing the following processing for each row:
- Set the current rowIndex to the appropriate value for this row.
- If isRowAvailable() returns true, iterate over the children components of each UIColumn child of this UIData component, calling the processValidators() method for each such child.
Set the current rowIndex to -1.

Overrides:: processValidators in class UIComponentBase

Parameters:: context - FacesContext for the current request
Throws:: NullPointerException - if context is null

processUpdates

public void processUpdates(FacesContext context)

Override the default UIComponentBase.processUpdates(javax.faces.context.FacesContext) processing to perform the following steps.

If the rendered property of this UIComponent is false, skip further processing.
Set the current rowIndex to -1.
Call the processUpdates() method of all facets of this UIData, in the order determined by a call to getFacets().keySet().iterator().
Call the processUpdates() method of all facets of the UIColumn children of this UIData.
Iterate over the set of rows that were included when this component was rendered (i.e. those defined by the first and rows properties), performing the following processing for each row:
- Set the current rowIndex to the appropriate value for this row.
- If isRowAvailable() returns true, iterate over the children components of each UIColumn child of this UIData component, calling the processUpdates() method for each such child.
Set the current rowIndex to -1.

Overrides:: processUpdates in class UIComponentBase

Parameters:: context - FacesContext for the current request
Throws:: NullPointerException - if context is null

getDataModel

protected DataModel getDataModel()

Return the internal DataModel object representing the data objects that we will iterate over in this component's rendering.

If the model has been cached by a previous call to setDataModel(javax.faces.model.DataModel), return it. Otherwise call getValue(). If the result is null, create an empty ListDataModel and return it. If the result is an instance of DataModel, return it. Otherwise, adapt the result as described in getValue() and return it.

setDataModel

protected void setDataModel(DataModel dataModel)

Set the internal DataModel. This UIData instance must use the given DataModel as its internal value representation from now until the next call to setDataModel. If the given DataModel is null, the internal DataModel must be reset in a manner so that the next call to getDataModel() causes lazy instantion of a newly refreshed DataModel.

Subclasses might call this method if they either want to restore the internal DataModel during the Restore View phase or if they want to explicitly refresh the current DataModel for the Render Response phase.

Parameters:: dataModel - the new DataModel or null to cause the model to be refreshed.