4.3 Iteration Status

You can specify a varStatus attribute for both the <c:forEach> and <c:forTokens> actions. The value of that attribute represents the name of a scoped variable that you can use to obtain information about the status of the iteration performed by those two actions; Table 4.2 lists the properties that you can access with that status object.

Table 4.2. `LoopTagStatus` Properties

Property	Type	Description
`current`	`Object`	The current item in the iteration.
`index`	`int`	If you are iterating over integer values, this property has the same value as the current item. If you are iterating over a data structure, this property represents the 0-based index of the current item; it tells you the index of the current item with respect to the underlying collection.
`count`	`int`	A `1` -based count of the current round of the iteration.
`first` ^[a]	`boolean`	This property tells whether the current round of the iteration is the first round ”it's only true when `count` is equal to `1` .
`last` ^[b]	`boolean`	This property tells whether the current round of the iteration is the last round ”it's only true when `count` is equal to `n` , where `n` represents the total number of iteration rounds.
`begin`	`Integer`	The value specified for the `begin` attribute.
`end`	`Integer`	The value specified for the `end` attribute.
`step`	`Integer`	The value specified for the `step` attribute.

^[a] The corresponding accessor method for the first property is isFirst , not getFirst .

^[b] The corresponding accessor method for the last property is isLast , not getLast .

The next two sections describe how to use status objects when you iterate over integer values with <c:forEach> and when you iterate over data structures with <c:forEach> or strings with <c:forTokens>.

Iteration Status for Integer Iterations

Figure 4-7 shows a JSP page that uses <c:forEach> to iterate over integer values. That JSP page lets you specify the begin , end , and step attributes for the <c:forEach> action and also displays information about the status of each round of the iteration.

Figure 4-7. Iteration Status for Iterating Over Integer Values

graphics/04fig07.jpg

The JSP page shown in Figure 4-7 is listed in Listing 4.6.

The preceding JSP page uses the <c:forEach> varStatus attribute to specify a scoped variable that is available only within the body of that action. That scoped variable is a status object that has the properties listed in Table 4.2 on page 171. The JSP page uses that scoped variable to print all of the status properties for each round of the iteration that <c:forEach> performs .

The picture shown in Figure 4-7 shows the result of specifying a begin attribute of 2 , an end attribute of 6 , and a step attribute of 1 . Notice that the index of the iteration is equal to the value of the current item, which is always the case when you iterate over integer values. The count property specifies the current round of the iteration and always starts with a value of 1 and increments by 1 for each round of the iteration. The isFirst property is true for the first round of the iteration, which coincides with a value of 1 for the count property. The isLast property is only true for the last round of the iteration, and the begin , end , and step properties coincide with the values specified for the begin , end , and step attributes of the <c:forEach> (or <c:forTokens>) action, respectively.

Listing 4.6 Iteration Status for Iterating Over Integer Values

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html>    <head>       <title>          Iteration Status for Iterating Over Integer Values       </title>    </head>    <body>       <%@ taglib uri='http://java.sun.com/jstl/core' prefix='c' %>       <%-- Because this form does not specify an action, this            JSP page will be reloaded when the submit button            is activated --%>       <form>          <table>             <tr>                <td>Begin:</td>                <td><input type='text' size='3'                          value='<c:out value="${param.begin}"/>'                           name='begin'/></td>                <td>End:</td>                <td><input type='text' size='3'                          value='<c:out value="${param.end}"/>'                           name='end'/></td>                <td>Step:</td>                <td><input type='text' size='3'                          value='<c:out value="${param.step}"/>'                           name='step'/></td>             </tr>          </table>          <p><input type='submit' value='Iterate Now'/>       </form>       <c:if test='${not empty param.begin and                     not empty param.end and                     not empty param.step}'>          <table border='1'>             <tr>                <%-- Create table headers --%>  <c:forEach var='item' items='Current,Index,Count,   Is First,Is Last,   Begin,End,Step'>   <th><c:out value='${item}'/></th>   </c:forEach>  </tr>             <%-- Loop over numeric values specified with                  request parameters --%>             <c:catch var='exception'>  <c:forEach varStatus='status'   begin='${param.begin}'   end='${param.end}'   step='${param.step}'>  <tr>                      <%-- Create table data --%>                      <td><c:out value='${status.current}'/></td>                      <td><c:out value='${status.index}'/></td>                      <td><c:out value='${status.count}'/></td>                      <td><c:out value='${status.first}'/></td>                      <td><c:out value='${status.last}'/></td>                      <td><c:out value='${status.begin}'/></td>                      <td><c:out value='${status.end}'/></td>                      <td><c:out value='${status.step}'/></td>                   </tr>  </c:forEach>  </c:catch>          </table>       </c:if>       <%-- Handle exceptions thrown by <c:forEach> --%>       <c:if test='${not empty exception}'>          <font color='red'>             Iteration failed because<i>             <c:out value='${exception.message}'/></i>          </font>       </c:if>    </body> </html>

Besides using status objects for integer iterations, you can also use them when you iterate over data structures, as illustrated in the next section.

Iteration Status for Data Structure Iterations

Using status objects for data structure iterations is the same as using them for integer iterations, but the index property or data structure iterations are different from the index property for integer iterations.

Figure 4-8 shows a JSP page that iterates over an array of strings representing numbers from 1 to 10 . That JSP page lets you specify the begin , end , and step attributes for the iteration.

Figure 4-8. Iteration Status for Iterating Over Data Structures

graphics/04fig08.jpg

The JSP page shown in Figure 4-8 is listed in Listing 4.7.

The preceding JSP page is similar to the JSP page shown in Figure 4-7 on page 172 and listed in Listing 4.6 on page 173. Both of those JSP pages use <c:forEach> to perform an iteration, and they both let you specify values for the <c:forEach> begin , end , and step attributes. Finally, both JSP pages use a status object, whose name is specified with the <c:forEach> varStatus attribute, to print all of the status properties.

In both cases, the results are similar: the count property represents the current round of the iteration and starts with 1 . The isFirst and isLast properties are boolean properties that reveal whether the current round of the iteration is the first or last, respectively. Finally, the begin , end , and step properties are fixed values that coincide with the begin , end , and step attributes specified for the <c:forEach> action.

The index status property is the only property that differs depending on whether you iterate over integer values or a data structure. As Figure 4-7 on page 172 illustrates, when you iterate over integer values, the index property coincides with the current property, but when you iterate over a data structure, the index property represents the index of the current item with respect to the underlying data structure. In the preceding JSP page, the starting index is specified with the <c:forEach> begin attribute as 2 , and therefore the first item in the iteration is the third string in the array ”remember that indexes for a collection are 0-based, so the first item in a collection has the index , the second item has the index 1 , the third item has the index 2 , and so on. Like the index status property for integer iterations, the index property for data structure iterations increases by the value that you specify for the <c:forEach> step attribute (which defaults to 1 ), as you can see from both Figure 4-8 on page 175 and Figure 4-7 on page 172.

Listing 4.7 Iterating Over an Array

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html>    <head>       <title>          Iteration Status for Iterating Over Numeric Values       </title>    </head>    <body>       <%@ taglib uri='http://java.sun.com/jstl/core' prefix='c' %>       <% // Create an array of strings          String[] values = { "ONE", "TWO", "THREE", "FOUR",                              "FIVE","SIX", "SEVEN", "EIGHT",                              "NINE","TEN" };          // Store the array in page scope          pageContext.setAttribute("values", values);       %>       <%-- Show the array of strings --%>       Iterating over this array of strings:  <c:forEach var='item' items='${values}'>  <c:out value='${item}'/>  </c:forEach>  <%-- Because this form does not specify an action, this            JSP page will be reloaded when the submit button            is activated --%>       <form>          <table>             <tr>                <td>Begin:</td>                <td><input type='text' size='3'                          value='<c:out value="${param.begin}"/>'                           name='begin'/></td>                <td>End:</td>                <td><input type='text' size='3'                          value='<c:out value="${param.end}"/>'                           name='end'/></td>                <td>Step:</td>                <td><input type='text' size='3'                          value='<c:out value="${param.step}"/>'                           name='step'/></td>             </tr>          </table>          <p><input type='submit' value='Iterate Now'/>       </form>       <c:if test='${not empty param.begin and                     not empty param.end and                     not empty param.step}'>          <table border='1'>             <tr>                <%-- Create table headers --%>  <c:forEach var='item' items='Current,Index,Count,   Is First,Is Last,Begin,   End,Step'>  <th><c:out value='${item}'/></th>  </c:forEach>  </tr>             <%-- Loop over an array of strings with looping                  attributes specified with request parameters --%>             <c:catch var='exception'>  <c:forEach items='${values}'   varStatus='status'   begin='${param.begin}'   end='${param.end}'   step='${param.step}'>  <tr>                      <%-- Create table data --%>                      <td><c:out value='${status.current}'/></td>                      <td><c:out value='${status.index}'/></td>                      <td><c:out value='${status.count}'/></td>                      <td><c:out value='${status.first}'/></td>                      <td><c:out value='${status.last}'/></td>                      <td><c:out value='${status.begin}'/></td>                      <td><c:out value='${status.end}'/></td>                      <td><c:out value='${status.step}'/></td>                   </tr>  </c:forEach>  </c:catch>          </table>       </c:if>       <%-- Handle exceptions thrown by <c:forEach> --%>       <c:if test='${not empty exception}'>          <font color='red'>             Iteration failed because<i>             <c:out value='${exception.message}'/></i>          </font>       </c:if>    </body> </html>