Iterator Tags — Functional Description

<forEach>
<forTokens>

1. Introduction

  <table>
    <c:forEach var="customer" items="$customers">
      <tr><td><c:expr value="$customer"/></td></tr>
    </c:forEach>
  </table>

• Supports all standard J2SE collection types.
• Exports an object that holds the current item of the iteration.
• Exports an object that holds information about the status of the iteration.
• Supports range attributes to iterate over a subset of the original collection.
• Exposes an interface as well as a base implementation class so developers can easily implement collaborating subtags as well their own iteration tags according to their specific needs.

2. Collection of objects to iterate over

• Array of Java Objects
• If the array contains a set of primitive types, then the current item for the iteration is automatically wrapped with its standard wrapper class (e.g. Integer for int, Float for float, etc...)
• Implementation of java.util.Collection. This includes among others: List, LinkedList, ArrayList, Vector, Stack, Set.
• Implementation of java.util.Iterator.
• Use with caution. An Iterator object is not resettable so it should not be used within more than one iteration tag.
• Implementation of java.util.Enumeration.
  • Use with caution. An Enumeration object is not resettable so it should not be used within more than one iteration tag.
• Implementation of java.util.Map. This includes among others: HashMap, Hashtable, Properties, Provider, Attributes. See below for additional information about accessing the current item of a Map.
• Implementation of java.sql.ResultSet, including javax.sql.RowSet. See below for additional information about accessing the current item of a ResultSet.
• String. The string represents a list of Comma Separated Values (e.g. "mon,tue,wed").

3. The current item

The current item of the iteration is made available via a JSP page scope attribute defined with attribute var. Attribute var has nested visibility, i.e. it only exists within the body of the <forEach> tag. At the end of the tag, the attribute is removed (no prior value is restored). Attribute var is optional. The page attribute is not created if a value is not defined for var.

Normally, each object exposed by the forEach tag is an item of the underlying collection being iterated over. However, if iterating over a Map or a ResultSet, the exposed object is as follows:

If items is of type Map, then the current item will be of type Map.Entry which has the following two properties:

• key - The key under which this item is stored in the underlying Map.
• value - The value that corresponds to this key.

  <c:forEach var="entry" items="$myHashtable"/>
    Next element is <c:expr value="$entry.value/>
  </c:forEach>

If items is of type ResultSet, then the current item is the ResultSet object itself positioned at the current row. Columns are accessed using the standard ResultSet API.

5. Iteration Status

This status information is accessible by defining a JSP page scope attribute via the status attribute. This page scope attribute has nested visibility, i.e. it only exists within the body of the <forEach> tag. At the end of the tag, the attribute is removed (no prior value is restored). This is an optional attribute with no default. No page attribute is exposed if a value is not specified for the status attribute.

In the example below, the JSP code creates an HTML table with the first column containing the position of the item in the collection, and the second containing the name of the employee.

  <table>
    <c:forEach var="employee" items="$employees" status="status">                                       
      <tr>
        <td><c:expr value="$status.count"/></td>
        <td><c:expr value="$employee.name"/></td>
      </tr>
    </c:forEach>
  </table>

6. Range Attributes

In this example, i would take values from 100 to 110 (included).

  <c:forEach var="i" begin="100" end="110">
    <c:expr value="$i"/>
  </c:forEach>

8. Attributes:

9. IteratorTagStatus

10. Tag Collaboration

In this example, a page author must handle an item of the iteration differently depending whether it is an odd or even element.

  <c:forEach var="product" items="products" status="status">
    <c:declare id="status" type="javax.servlet.jsp.jstl.core.IteratorTagStatus"/>
    <c-rt:choose>
      <c-rt:when test="<%= status.getCount() % 2 == 0 %>">
        <!-- even item -->
      </c-rt:when>
      <c-rt:otherwise>
        <!-- odd item -->
      </c-rt:otherwise>
    </c-rt:choose>
  </c:forEach>

If this type of processing needs to be repeated often in the web applications of a company, it might be worth to provide page authors with a couple extra tags that would remove the need for conditional tags and expressions. For example:

  <c:forEach items="$products">
    <xyz:even>
      <!-- even item -->
    </xyz:even>
    <xyz:odd>
      <!-- odd item -->
    </xyz:odd>
  </c:forEach>

In order to make this possible, tags like <odd> and <even> need to be able to get access to the information exported by the forEach tag. This could be done explicitely, by specifying the name of the status object exported by the forEach tag. For example:

  <c:forEach items="<%=products%>" status="status">
    <xyz:even iter="status">
      <!-- even item -->
    </xyz:even>
    <xyz:odd iter="status">
      <!-- odd item -->
    </xyz:odd>
  </c:forEach>

The cooperation between these tags and the forEach tag can also be done implicitely via the findAncestorWithClass() method of the JSP API. This is possible because the forEach tag implements an interface that can be used in the call to findAncestorWithClass to get to the enclosing forEach tag.

The interface is defined as follows:

  interface IteratorTag {
    public Object getCurrent();
    public IteratorTagStatus getIteratorStatus();
  }

Interface IteratorTagStatus was described in a previous section.

The fact that the forEach tag exposes an interface also means that other tags with iterative behavior can be developed using the same interface and will collaborate in the same manner with nested tags. See class IteratorTagSupport below to make this process even easier.

11. Tag Extensibility

However, there will be situations where more specialized functionality will be required. A developer may need to write a new tag to expose new controlling functionality (e.g. for traversal order of a deep data structure, custom filtering, selection of appropriate objects from a custom data source). This is why the IteratorTagSupport class is provided. It will facilitate the implementation of specialized iterator tags that will meet an application's specific requirements.

  public abstract class IteratorTagSupport {
     ... (see source code)...
  }