|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.faces.component.UIComponent
javax.faces.component.UIComponentBase
javax.faces.component.UIData
public class UIData
Represents a component which has multiple "rows" of data.
The children of this component are expected to be UIColumn components.
Note that the same set of child components are reused to implement each row of the table in turn during such phases as apply-request-values and render-response. Altering any of the members of these components therefore affects the attribute for every row, except for the following members:
This reuse of the child components also means that it is not possible to save a reference to a component during table processing, then access it later and expect it to still represent the same row of the table.
Each of the UIColumn children of this component has a few component children of its own to render the contents of the table cell. However there can be a very large number of rows in a table, so it isn't efficient for the UIColumn and all its child objects to be duplicated for each row in the table. Instead the "flyweight" pattern is used where a serialized state is held for each row. When setRowIndex is invoked, the UIColumn objects and their children serialize their current state then reinitialise themselves from the appropriate saved state. This allows a single set of real objects to represent multiple objects which have the same types but potentially different internal state. When a row is selected for the first time, its state is set to a clean "initial" state. Transient components (including any read-only component) do not save their state; they are just reinitialised as required. The state saved/restored when changing rows is not the complete component state, just the fields that are expected to vary between rows: "submittedValue", "value", "isValid".
Note that a table is a "naming container", so that components within the table have their ids prefixed with the id of the table. Actually, when setRowIndex has been called on a table with id of "zzz" the table pretends to its children that its ID is "zzz_n" where n is the row index. This means that renderers for child components which call component.getClientId automatically get ids of form "zzz_n:childId" thus ensuring that components in different rows of the table get different ids.
When decoding a submitted page, this class iterates over all its possible rowIndex values, restoring the appropriate serialized row state then calling processDecodes on the child components. Because the child components (or their renderers) use getClientId to get the request key to look for parameter data, and because this object pretends to have a different id per row ("zzz_n") a single child component can decode data from each table row in turn without being aware that it is within a table. The table's data model is updated before each call to child.processDecodes, so the child decode method can assume that the data model's rowData points to the model object associated with the row currently being decoded. Exactly the same process applies for the later validation and updateModel phases.
When the data model for the table is bound to a backing bean property, and no validation errors have occured during processing of a postback, the data model is refetched at the start of the rendering phase (ie after the update model phase) so that the contents of the data model can be changed as a result of the latest form submission. Because the saved row state must correspond to the elements within the data model, the row state must be discarded whenever a new data model is fetched; not doing this would cause all sorts of inconsistency issues. This does imply that changing the state of any of the members "submittedValue", "value" or "valid" of a component within the table during the invokeApplication phase has no effect on the rendering of the table. When a validation error has occurred, a new DataModel is not fetched, and the saved state of the child components is not discarded.
see Javadoc of JSF Specification for more.
Field Summary | |
---|---|
static java.lang.String |
COMPONENT_FAMILY
|
static java.lang.String |
COMPONENT_TYPE
|
Fields inherited from interface javax.faces.component.NamingContainer |
---|
SEPARATOR_CHAR |
Constructor Summary | |
---|---|
UIData()
|
Method Summary | |
---|---|
void |
broadcast(FacesEvent event)
Ensure that before the event's listeners are invoked this UIData component's "current row" is set to the row associated with the event. |
void |
encodeBegin(FacesContext context)
Perform necessary actions when rendering of this component starts, before delegating to the inherited implementation which calls the associated renderer's encodeBegin method. |
void |
encodeEnd(FacesContext context)
|
java.lang.String |
getClientId(FacesContext context)
Get a string which can be output to the response which uniquely identifies this UIComponent within the current view. |
java.lang.String |
getFamily()
|
int |
getFirst()
|
UIComponent |
getFooter()
|
UIComponent |
getHeader()
|
int |
getRowCount()
|
java.lang.Object |
getRowData()
|
int |
getRowIndex()
|
int |
getRows()
|
java.lang.Object |
getValue()
|
java.lang.String |
getVar()
|
boolean |
isRowAvailable()
|
void |
processDecodes(FacesContext context)
|
void |
processUpdates(FacesContext context)
This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components. |
void |
processValidators(FacesContext context)
|
void |
queueEvent(FacesEvent event)
Modify events queued for any child components so that the UIData state will be correctly configured before the event's listeners are executed. |
void |
restoreState(FacesContext context,
java.lang.Object state)
Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object. |
java.lang.Object |
saveState(FacesContext context)
Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has. |
void |
setFirst(int first)
|
void |
setFooter(UIComponent footer)
|
void |
setHeader(UIComponent header)
|
void |
setRowIndex(int rowIndex)
Set the current row index that methods like getRowData use. |
void |
setRows(int rows)
Set the maximum number of rows displayed in the table. |
void |
setValue(java.lang.Object value)
|
void |
setValueBinding(java.lang.String name,
ValueBinding binding)
Put the provided value-binding into a map of value-bindings associated with this component. |
void |
setVar(java.lang.String var)
Set the name of the temporary variable that will be exposed to child components of the table to tell them what the "rowData" object for the current row is. |
Methods inherited from class javax.faces.component.UIComponentBase |
---|
addFacesListener, decode, encodeChildren, findComponent, getAttributes, getChildCount, getChildren, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, isRendered, isTransient, processRestoreState, processSaveState, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String COMPONENT_TYPE
public static final java.lang.String COMPONENT_FAMILY
Constructor Detail |
---|
public UIData()
Method Detail |
---|
public void setFooter(UIComponent footer)
public UIComponent getFooter()
public void setHeader(UIComponent header)
public UIComponent getHeader()
public boolean isRowAvailable()
public int getRowCount()
public java.lang.Object getRowData()
public int getRowIndex()
public void setRowIndex(int rowIndex)
Param rowIndex can be -1, meaning "no row".
rowIndex
- public void setRows(int rows)
public void setVar(java.lang.String var)
public java.lang.String getVar()
public void setValueBinding(java.lang.String name, ValueBinding binding)
UIComponentBase
setValueBinding
in class UIComponentBase
public java.lang.String getClientId(FacesContext context)
UIComponentBase
The component should have an id attribute already assigned to it; however if the id property is currently null then a unique id is generated and set for this component. This only happens when components are programmatically created without ids, as components created by a ViewHandler should be assigned ids when they are created.
If this component is a descendant of a NamingContainer then the client id is of form "{namingContainerId}:{componentId}". Note that the naming container's id may itself be of compound form if it has an ancestor naming container. Note also that this only applies to naming containers; other UIComponent types in the component's ancestry do not affect the clientId.
Finally the renderer associated with this component is asked to convert the id into a suitable form. This allows escaping of any characters in the clientId which are significant for the markup language generated by that renderer.
getClientId
in class UIComponentBase
public void queueEvent(FacesEvent event)
Child components or their renderers may register events against those child components. When the listener for that event is eventually invoked, it may expect the uidata's rowData and rowIndex to be referring to the same object that caused the event to fire.
The original queueEvent call against the child component has been forwarded up the chain of ancestors in the standard way, making it possible here to wrap the event in a new event whose source is this component, not the original one. When the event finally is executed, this component's broadcast method is invoked, which ensures that the UIData is set to be at the correct row before executing the original event.
queueEvent
in class UIComponentBase
public void broadcast(FacesEvent event) throws AbortProcessingException
See queueEvent for more details.
broadcast
in class UIComponentBase
event
- must not be null.
AbortProcessingException
public void encodeBegin(FacesContext context) throws java.io.IOException
encodeBegin
in class UIComponentBase
java.io.IOException
public void encodeEnd(FacesContext context) throws java.io.IOException
encodeEnd
in class UIComponentBase
java.io.IOException
UIComponentBase.encodeEnd(javax.faces.context.FacesContext)
public void processDecodes(FacesContext context)
processDecodes
in class UIComponentBase
public void processValidators(FacesContext context)
processValidators
in class UIComponentBase
public void processUpdates(FacesContext context)
UIComponentBase
Components that were never rendered can't possibly be receiving update data (no corresponding fields were ever put into the response) so if this component is not rendered then this method does not invoke processUpdates on its children.
processUpdates
in class UIComponentBase
public void setValue(java.lang.Object value)
public java.lang.Object saveState(FacesContext context)
UIComponentBase
saveState
in interface StateHolder
saveState
in class UIComponentBase
public void restoreState(FacesContext context, java.lang.Object state)
UIComponentBase
restoreState
in interface StateHolder
restoreState
in class UIComponentBase
state
- is an object previously returned by
the saveState method of this class.public java.lang.String getFamily()
getFamily
in class UIComponent
public void setFirst(int first)
public int getFirst()
public int getRows()
public java.lang.Object getValue()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |