org.apache.myfaces.trinidad.component

## Class UIXIterator

- java.lang.Object
- - javax.faces.component.UIComponent
  - - org.apache.myfaces.trinidad.component.UIXComponent
    - - org.apache.myfaces.trinidad.component.UIXComponentBase
      - - org.apache.myfaces.trinidad.component.UIXCollection
        - - org.apache.myfaces.trinidad.component.UIXIterator

- All Implemented Interfaces:
    EventListener, javax.faces.component.NamingContainer, javax.faces.component.PartialStateHolder, javax.faces.component.StateHolder, javax.faces.component.TransientStateHolder, javax.faces.event.ComponentSystemEventListener, javax.faces.event.FacesListener, javax.faces.event.SystemEventListenerHolder, FlattenedComponent, LocalRowKeyIndex
  Direct Known Subclasses:
    UIXListView, UIXTable

      public class UIXIterator
      extends UIXCollection
      implements LocalRowKeyIndex, FlattenedComponent

  UIXIterator is a component that performs iteration over its child components. It is similar to UIXTable but has no chrome. Each child is repeatedly stamped as many times as necessary. Iteration is done starting at the index given by the "first" attribute, for as many indices as specified by the "rows" attribute. If "rows" returns 0, then the iteration continues until there are no more elements in the underlying data.

  While the <tr:forEach> will be sufficient for most user's needs, it does not work with a JSF DataModel, or CollectionModel. It also cannot be bound to EL expressions that use component-managed EL variables (such as the "var" variable on an <tr:table>), because a forEach tag runs during The <tr:iterator> tag was created to address these issues.

  To list all, the benefits of UIXIterator over forEach:

  - Access to component-managed EL variables
  - Full support for CollectionModel and DataModel
  - Does not require creating multiple copies of children, so more memory efficient
  - Much better at dealing with adding and deleting children, at least when used with a CollectionModel with a good implementation of getRowKey()
  - Supports "binding", and all other forms of JSF component manipulation
  and the negative aspects:
  - Leaves behind a component in the hierarchy, which causes problems with components like panelFormLayout that try to handle each child individually.
  - Because there's only one of each child, the same limitations on "binding", etc., as apply inside a table also apply to iterator.

  By default, it processes up to 25 rows. Use the rows attribute to alter this behavior.

  #### Events:

  Type | Phases | Description
  --- | --- | ---
  `org.apache.myfaces.trinidad.event.AttributeChangeEvent` | Invoke Application Apply Request Values | Event delivered to describe an attribute change. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change event might include the width of a column that supported client-side resizing.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.myfaces.trinidad.component.UIXCollection

      `UIXCollection.NoColumnFacetsVisitContext`

    - ### Nested classes/interfaces inherited from class org.apache.myfaces.trinidad.component.UIXComponentBase

      `UIXComponentBase.ComponentSystemEventListenerWrapper`

    - ### 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 String` | `COMPONENT_FAMILY`
    `static String` | `COMPONENT_TYPE`
    `static PropertyKey` | `FIRST_KEY`
    `static PropertyKey` | `ROWS_KEY`
    `static FacesBean.Type` | `TYPE`
    `static PropertyKey` | `VALUE_KEY`
    `static PropertyKey` | `VAR_STATUS_KEY`

    - ### Fields inherited from class org.apache.myfaces.trinidad.component.UIXCollection

      `VAR_KEY`

    - ### Fields inherited from class org.apache.myfaces.trinidad.component.UIXComponentBase

      `BINDING_KEY, ID_KEY, RENDERED_KEY, RENDERER_TYPE_KEY, TRANSIENT_KEY`

    - ### Fields inherited from class javax.faces.component.UIComponent

      `ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY`

    - ### Fields inherited from interface javax.faces.component.NamingContainer

      `SEPARATOR_CHAR`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `UIXIterator()` Construct an instance of the UIXIterator.
    `protected` | `UIXIterator(String rendererType)` Construct an instance of the UIXIterator.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected CollectionModel` | `createCollectionModel(CollectionModel current, Object value)` Creates the CollectionModel to use with this component.
    `protected Map<String,Object>` | `createVarStatusMap()` Enhances the varStatusMap created by the super class to include: begin - the index of the first row being rendered first - true if the current row is the first row count - indicates which iteration this is.
    `void` | `encodeChildren(javax.faces.context.FacesContext context)` Repeatedly render the children as many times as needed.
    `protected FacesBean.Type` | `getBeanType()`
    `String` | `getFamily()`
    `int` | `getFirst()` Gets the index of the first row in the currently range of rows.
    `boolean` | `getRendersChildren()` Override to return true.
    `int` | `getRows()` Gets the maximum number of rows to display in a single range of rows.
    `Object` | `getValue()` Gets the data model being used by this component.
    `String` | `getVarStatus()` Gets Name of the EL variable used to reference the varStatus information.
    `boolean` | `isFlatteningChildren(javax.faces.context.FacesContext context)` Returns `true` if this FlattenedComponent is currently flattening its children
    `protected void` | `processFacetsAndChildren(javax.faces.context.FacesContext context, javax.faces.event.PhaseId phaseId)` Process this component's facets and children.
    `<S> boolean` | `processFlattenedChildren(javax.faces.context.FacesContext context, ComponentProcessingContext cpContext, ComponentProcessor<S> childProcessor, S callbackContext)` Sets up the iteration context for each child and processes it
    `void` | `setFirst(int first)` Sets the index of the first row in the currently range of rows.
    `void` | `setRows(int rows)` Sets the maximum number of rows to display in a single range of rows.
    `void` | `setValue(Object value)` Sets the data model being used by this component.
    `void` | `setVarStatus(String varStatus)` Sets Name of the EL variable used to reference the varStatus information.
    `protected boolean` | `visitData(javax.faces.component.visit.VisitContext visitContext, javax.faces.component.visit.VisitCallback visitCallback)` Visit the rows and children of the columns of the collection per row-index.

    - ### Methods inherited from class org.apache.myfaces.trinidad.component.UIXCollection

      `areRowsAvailable, areRowsAvailable, areRowsAvailable, areRowsLocallyAvailable, areRowsLocallyAvailable, areRowsLocallyAvailable, broadcast, clearCachedRow, clearCachedRow, clearCachedRows, clearCachedRows, clearCurrencyStringCache, clearLocalCache, decodeChildrenImpl, defaultVisitChildren, encodeBegin, encodeEnd, ensureRowsAvailable, getCachingStrategy, getClientRowKey, getClientRowKeyManager, getCollectionModel, getCollectionModel, getContainerClientId, getCurrencyString, getEstimatedRowCount, getEstimatedRowCountConfidence, getRowCount, getRowData, getRowData, getRowData, getRowIndex, getRowKey, getSortCriteria, getStamps, getVar, invokeOnComponent, isRowAvailable, isRowAvailable, isRowAvailable, isRowLocallyAvailable, isRowLocallyAvailable, isSortable, postCreateCollectionModel, postRowDataChange, preRowDataChange, processComponent, processDecodes, processEvent, processFlattenedChildrenBegin, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, resetStampState, restoreStampState, restoreState, saveStampState, saveState, setClientRowKey, setCurrencyString, setRowIndex, setRowKey, setSortCriteria, setupELVariable, setupVisitingContext, setVar, tearDownVisitingContext, updateChildrenImpl, validateChildrenImpl, visitChildren, visitChildrenWithoutIterating, visitUnstampedFacets`

    - ### Methods inherited from class org.apache.myfaces.trinidad.component.UIXComponentBase

      `adaptMethodBinding, addAttributeChange, addAttributeChangeListener, addClientBehavior, addComponentChange, addComponentChange, addComponentChangeFilter, addFacesListener, broadcastToMethodBinding, broadcastToMethodExpression, clearCachedClientIds, clearInitialState, createFacesBean, decode, decodeChildren, findComponent, getAttributeChangeListener, getAttributeChangeListeners, getAttributes, getBooleanProperty, getChildCount, getChildren, getClientBehaviors, getClientId, getComponentChangeFilters, getContainerClientId, getDefaultEventName, getFacesBean, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacetNames, getFacets, getFacetsAndChildren, getId, getIntProperty, getLifecycleRenderer, getListenersForEventClass, getParent, getProperty, getPropertyKey, getRenderedFacetsAndChildren, getRenderer, getRendererType, getValueBinding, getValueExpression, initialStateMarked, invokeOnChildrenComponents, invokeOnNamingContainerComponent, isRendered, isTransient, markInitialState, removeAttributeChangeListener, removeComponentChangeFilter, removeFacesListener, satisfiesPartialTrigger, setAttributeChangeListener, setAttributeChangeListener, setBooleanProperty, setId, setIntProperty, setParent, setProperty, setRendered, setRendererType, setTransient, setupFlattenedChildrenContext, setupFlattenedContext, setValueBinding, setValueExpression, subscribeToEvent, tearDownFlattenedChildrenContext, tearDownFlattenedContext, toString, unsubscribeFromEvent, updateChildren, validateChildren`

    - ### Methods inherited from class org.apache.myfaces.trinidad.component.UIXComponent

      `addPartialTarget, broadcastInContext, clearCachedClientIds, defaultGetRenderedFacetsAndChildren, encodeFlattenedChild, encodeFlattenedChildren, getLogicalParent, getLogicalParent, getStateHelper, getStateHelper, isVisitable, partialEncodeVisit, processFlattenedChildren, processFlattenedChildren, processFlattenedChildren, processFlattenedChildren, setPartialTarget, setupChildrenEncodingContext, setupChildrenVisitingContext, setupEncodingContext, setUpEncodingContext, tearDownChildrenEncodingContext, tearDownChildrenVisitingContext, tearDownEncodingContext, visitAllChildren, visitChildren, visitTree, visitTree`

    - ### Methods inherited from class javax.faces.component.UIComponent

      `encodeAll, getClientId, getCompositeComponentParent, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getResourceBundleMap, getTransientStateHelper, getTransientStateHelper, isCompositeComponent, isInView, popComponentFromEL, pushComponentToEL, restoreTransientState, saveTransientState, setInView`

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

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

    - ### Methods inherited from interface org.apache.myfaces.trinidad.model.LocalRowKeyIndex

      `areRowsLocallyAvailable, areRowsLocallyAvailable, areRowsLocallyAvailable, clearCachedRow, clearCachedRow, clearCachedRows, clearCachedRows, clearLocalCache, getCachingStrategy, getEstimatedRowCount, getEstimatedRowCountConfidence, isRowLocallyAvailable, isRowLocallyAvailable`

- - ### Field Detail

    - #### TYPE

          public static final FacesBean.Type TYPE

    - #### VAR_STATUS_KEY

          public static final PropertyKey VAR_STATUS_KEY

    - #### VALUE_KEY

          public static final PropertyKey VALUE_KEY

    - #### ROWS_KEY

          public static final PropertyKey ROWS_KEY

    - #### FIRST_KEY

          public static final PropertyKey FIRST_KEY

    - #### COMPONENT_FAMILY

          public static final String COMPONENT_FAMILY

      See Also:
        Constant Field Values

    - #### COMPONENT_TYPE

          public static final String COMPONENT_TYPE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UIXIterator

          public UIXIterator()

      Construct an instance of the UIXIterator.

    - #### UIXIterator

          protected UIXIterator(String rendererType)

      Construct an instance of the UIXIterator.

  - ### Method Detail

    - #### getRendersChildren

          public boolean getRendersChildren()

      Override to return true.
      Overrides:
        `getRendersChildren` in class `UIXComponentBase`

    - #### processFlattenedChildren

          public <S> boolean processFlattenedChildren(javax.faces.context.FacesContext context,
                                             ComponentProcessingContext cpContext,
                                             ComponentProcessor<S> childProcessor,
                                             S callbackContext)
                                           throws IOException

      Sets up the iteration context for each child and processes it
      Specified by:
        `processFlattenedChildren` in interface `FlattenedComponent`
      Parameters:
        `context` - Current FacesContext
        `cpContext` - ComponentProcesingContext represetning the current child iteration state
        `childProcessor` - ComponentProcessor to call for each flattened child
        `callbackContext` - childProcessor-specific context to be passed on each call to the childProcessor
      Returns:
        `true` if this FlattenedComponent actually processed any children
      Throws:
        `IOException` - if an error occurs while processing children
      See Also:
        `UIXComponent.processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)`, `UIXComponent.processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)`, `FlattenedComponent.isFlatteningChildren(javax.faces.context.FacesContext)`

    - #### isFlatteningChildren

          public boolean isFlatteningChildren(javax.faces.context.FacesContext context)

      Returns `true` if this FlattenedComponent is currently flattening its children
      Specified by:
        `isFlatteningChildren` in interface `FlattenedComponent`
      Parameters:
        `context` - FacesContext
      Returns:
        `true` if this FlattenedComponent is currently flattening its children
      See Also:
        `FlattenedComponent.processFlattenedChildren(javax.faces.context.FacesContext, org.apache.myfaces.trinidad.component.ComponentProcessingContext, org.apache.myfaces.trinidad.component.ComponentProcessor<S>, S)`

    - #### encodeChildren

          public void encodeChildren(javax.faces.context.FacesContext context)
                              throws IOException

      Repeatedly render the children as many times as needed.
      Overrides:
        `encodeChildren` in class `UIXComponentBase`
      Throws:
        `IOException`

    - #### createVarStatusMap

          protected Map<String,Object> createVarStatusMap()

      Enhances the varStatusMap created by the super class to include:
      - begin - the index of the first row being rendered
      - first - true if the current row is the first row
      - count - indicates which iteration this is. This always starts at one, and increases (by one) as the loop progresses.
      - step - this is always one.
      Overrides:
        `createVarStatusMap` in class `UIXCollection`

    - #### createCollectionModel

          protected CollectionModel createCollectionModel(CollectionModel current,
                                              Object value)

      Description copied from class: `UIXCollection`
      Creates the CollectionModel to use with this component. The state of the UIComponent with the new model instance is not fully initialized until after this method returns. As a result, other component attributes that need a fully initialized model should not be initialized in this method. Instead, model-dependent initialization should be done in `postCreateCollectionModel`
      Specified by:
        `createCollectionModel` in class `UIXCollection`
      Parameters:
        `current` - the current CollectionModel, or null if there is none.
        `value` - this is the value returned from `UIXCollection.getValue()`
      See Also:
        `UIXCollection.postCreateCollectionModel(org.apache.myfaces.trinidad.model.CollectionModel)`

    - #### processFacetsAndChildren

          protected void processFacetsAndChildren(javax.faces.context.FacesContext context,
                                      javax.faces.event.PhaseId phaseId)

      Description copied from class: `UIXCollection`
      Process this component's facets and children. This method should call `UIXCollection.processComponent(javax.faces.context.FacesContext, javax.faces.component.UIComponent, javax.faces.event.PhaseId)` as many times as necessary for each facet and child. `UIXCollection.processComponent(javax.faces.context.FacesContext, javax.faces.component.UIComponent, javax.faces.event.PhaseId)` may be called repeatedly for the same child if that child is being stamped.
      Specified by:
        `processFacetsAndChildren` in class `UIXCollection`

    - #### visitData

          protected boolean visitData(javax.faces.component.visit.VisitContext visitContext,
                          javax.faces.component.visit.VisitCallback visitCallback)

      Description copied from class: `UIXCollection`
      Visit the rows and children of the columns of the collection per row-index. This should not visit row index -1 (it will be perfomed in the visitTree method). The columns themselves should not be visited, only their children in this function.
      Specified by:
        `visitData` in class `UIXCollection`
      Parameters:
        `visitContext` - The visiting context
        `visitCallback` - The visit callback
      Returns:
        true if the visiting should stop
      See Also:
        `UIXCollection.visitChildren(VisitContext, VisitCallback)`

    - #### getVarStatus

          public final String getVarStatus()

      Gets
      Name of the EL variable used to reference the varStatus information. Once this component has completed rendering, this variable is removed (or reverted back to its previous value). The VarStatus provides contextual information about the state of the component to EL expressions. For components that iterate, varStatus also provides loop counter information. Please see the this component's documentation for the specific properties on the varStatus. The common properties on varStatus include:
      - "model" - returns the CollectionModel for this component.
      - "index" - returns the zero based row index.
      - "hierarchicalIndex" - returns an array containing zero based row index.
      - "hierarchicalLabel" - returns a string label representing 1 based index of this row.
      - "rowKey" - returns the current rowKey in the collection.
      - "current" - returns the current row in the collection.
      Specified by:
        `getVarStatus` in class `UIXCollection`
      Returns:
        the new varStatus value
      See Also:
        `UIXCollection.createVarStatusMap()`

    - #### setVarStatus

          public final void setVarStatus(String varStatus)

      Sets
      Name of the EL variable used to reference the varStatus information. Once this component has completed rendering, this variable is removed (or reverted back to its previous value). The VarStatus provides contextual information about the state of the component to EL expressions. For components that iterate, varStatus also provides loop counter information. Please see the this component's documentation for the specific properties on the varStatus. The common properties on varStatus include:
      - "model" - returns the CollectionModel for this component.
      - "index" - returns the zero based row index.
      - "hierarchicalIndex" - returns an array containing zero based row index.
      - "hierarchicalLabel" - returns a string label representing 1 based index of this row.
      - "rowKey" - returns the current rowKey in the collection.
      - "current" - returns the current row in the collection.
      Parameters:
        `varStatus` - the new varStatus value

    - #### getValue

          public final Object getValue()

      Gets the data model being used by this component. The specific model class is `org.apache.myfaces.trinidad.model.CollectionModel`. You may also use other model instances, e.g., `java.util.List` , array, and `javax.faces.model.DataModel`. This component will automatically convert the instance into a `CollectionModel`.
      Specified by:
        `getValue` in class `UIXCollection`
      Returns:
        the new value value

    - #### setValue

          public final void setValue(Object value)

      Sets the data model being used by this component. The specific model class is `org.apache.myfaces.trinidad.model.CollectionModel`. You may also use other model instances, e.g., `java.util.List` , array, and `javax.faces.model.DataModel`. This component will automatically convert the instance into a `CollectionModel`.
      Parameters:
        `value` - the new value value

    - #### getRows

          public final int getRows()

      Gets the maximum number of rows to display in a single range of rows. Some ranges might have fewer than the number of rows specified by this attribute (eg: the last range might have an insufficient number of rows). To display all rows at once, set this attribute to 0. The default is 25.
      Returns:
        the new rows value

    - #### setRows

          public final void setRows(int rows)

      Sets the maximum number of rows to display in a single range of rows. Some ranges might have fewer than the number of rows specified by this attribute (eg: the last range might have an insufficient number of rows). To display all rows at once, set this attribute to 0. The default is 25.
      Parameters:
        `rows` - the new rows value

    - #### getFirst

          public final int getFirst()

      Gets the index of the first row in the currently range of rows. This index is zero-based. This attribute is used to control which range of rows to display to the user.
      Returns:
        the new first value

    - #### setFirst

          public final void setFirst(int first)

      Sets the index of the first row in the currently range of rows. This index is zero-based. This attribute is used to control which range of rows to display to the user.
      Parameters:
        `first` - the new first value

    - #### getFamily

          public String getFamily()

      Specified by:
        `getFamily` in class `UIXComponentBase`

    - #### getBeanType

          protected FacesBean.Type getBeanType()

      Overrides:
        `getBeanType` in class `UIXComponentBase`

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