11.4 Iteration Actions

JSTL provides two actions that you can use to iterate over various types of data:

• <c:forEach>

• <c:forTokens>

An overview of the actions listed above is provided in the following pages. A more in-depth examination of those actions can be found in "Iteration Actions" on page 150.

JSTL also provides an interface and two classes that let you develop custom iteration actions and access an iteration's status:

• LoopTag (interface)

• LoopTagSupport (class)

• LoopTagStatus (class)

An overview of the interface and classes listed above can be found at "Exposed Classes and Interfaces" on page 483. You can also find an in-depth examination of accessing loop status at "Iteration Status" on page 171 and implementing custom iteration actions in "Custom Iteration Actions" on page 178.

JSTL Iteration Actions

<c:forEach>

Iterates over integer values or a data structure

Syntax: ^[7]

^[7] Items in brackets are optional.

Syntax #1: Iterates over a collection of objects

 <c:forEach items [begin] [end] [step] [var] [varStatus]>  body content  </c:forEach> 

Syntax #2: Iterates over a set of integer values

 <c:forEach begin end [step] [var] [varStatus]>  body content  </c:forEach> 

Description:

You can use the <c:forEach> action to iterate over a data structure, such as an array, map, or collection if you specify that data structure with the items attribute. You can also use <c:forEach> to iterate over integer values if you don't specify the items attribute.

Attributes:

Attribute [a]	Type	Description
items	String, Array, Collection, Iterator, Enumeration, Map	The items that <c:forEach> iterates over. This attribute is not specified when you iterate over explicit integer values.
begin	int	If you iterate over explicit integer values, this attribute specifies the starting value. If you iterate over a data structure, this attribute specifies the index of the first item that's accessed in that data structure.
end	int	If you iterate over explicit integer values, this attribute specifies the ending value. If you iterate over a data structure, this attribute specifies the index of the last item that is potentially accessed in that data structure.
step	int	The amount that the loop index is incremented for every round of an iteration.
var	String	The name of a scoped variable that references the iteration's current item. If you iterate over explicit integer values, that scoped variable contains the current integer value; if you iterate over a data structure, it contains the current object from that data structure.
varStatus	String	The name of a scoped variable that references an object that has properties corresponding to the status of the iteration. That object's type is LoopTagStatus .

^[a] static dynamic

Constraints and Error Handling:

• If you specify the begin attribute, its value must be greater than or equal to zero.

• If you specify the end attribute, its value must be greater than or equal to the value that you specify for the begin attribute.

• If you specify the step attribute, its value must be greater than or equal to 1.

In a Nutshell:

The <c:forEach> action can iterate over integer values or a data structure that can be one of the following: map, collection, array, or a comma-separated string. The <c:forEach> action can also use an iterator or an enumeration to iterate over an underlying collection.

<c:forTokens>

Iterates over tokens in a string

Syntax: ^[8]

^[8] Items in brackets are optional.

 <c:forTokens items delims [begin] [end] [step] [var] [varStatus]>  body content  </c:forTokens> 

Description:

The <c:forTokens> action iterates over a string of tokens delimited by delimiters that you specify with the delims attribute.

Attributes:

Attribute [a]	Type	Description
items	String	A string that <c:forTokens> iterates over. Tokens in the string are delimited by the delimiters specified with the delims attribute.
begin	int	A zero-based index that represents the first token that <c:forTokens> iterates over.
end	int	A zero-based index that represents the last token that is potentially accessed in the string specified with the items attribute.
step	int	The amount that the loop index is incremented for every round of an iteration.
var	String	The name of a scoped variable that references the iteration's current item.
varStatus	String	The name of a scoped variable that references an object that has properties corresponding to the status of the iteration. That object's type is LoopTagStatus .

^[a] static dynamic

Constraints and Error Handling:

• If you specify the begin attribute, its value must be greater than or equal to zero.

• If you specify the end attribute, its value must be greater than or equal to the value that you specify for the begin attribute.

• If you specify the step attribute, its value must be greater than or equal to 1.

In a Nutshell:

The <c:forEach> action can iterate over tokens in a string as long as those tokens are delimited by commas. If you need to iterate over a string whose tokens are delimited by characters other than commas, you can use the <c:forTokens> action. The <c:forTokens> action is especially handy when you need to iterate over strings with multiple tokens that represent nested data; see "The <c:forTokens> Action" on page 166 for an example of that usage.

Exposed Classes and Interfaces

The JSTL iteration actions expose one interface and two classes:

• javax.servlet.jsp.jstl. core .LoopTag (interface)

• javax.servlet.jsp.jstl.core.LoopTagSupport (class)

• javax.servlet.jsp.jstl.core.LoopTagStatus (class)

The classes and interface listed above are discussed below.

LoopTag

An interface implemented by the <c:forEach> and <c:forTokens> tag handlers

Definition:

 interface LoopTag {       public Object getCurrent()      public LoopTagStatus getLoopStatus() } 

Description:

The <c:forEach> and <c:forTokens> actions have tag handlers that implement the LoopTag interface. You can take advantage of that implementation to implement custom actions that collaborate with <c:forEach> and <c:forTokens> actions; see "Collaboration Custom Actions" on page 178 for more information about implementing collaboration custom actions.

LoopTagSupport

The superclass for <c:forEach> and <c:forTokens> tag handlers

Definition:

 class LoopTagSupport {       public LoopTagSupport()      protected abstract Object next() throws JspTagException      protected abstract boolean hasNext() throws JspTagException      protected abstract void prepare() throws JspTagException      protected void validateBegin() throws JspTagException      protected void validateEnd() throws JspTagException      protected void validateStep() throws JspTagException      public Object getCurrent() throws JspTagException      public LoopTagStatus getLoopStatus()      public void setVar(String)      public void setVarStatus(String) } 

Description:

To implement iteration custom actions, extend the LoopTagSupport class, which provides convenience methods for implementing those types of custom actions. The LoopTagSupport class is also the superclass of the <c:forEach> and <c:forTokens> tag handlers. See "Custom Iteration Actions" on page 178 for more information about developing iteration custom actions.

LoopTagStatus

A class that provides information about an iteration's status

Definition:

 class LoopTagStatus {       public Object getCurrent()      public int getIndex()      public int getCount()      public boolean isFirst()      public boolean isLast()      public Integer getBegin()      public Integer getEnd()      public Integer getStep() } 

Description:

The LoopTagStatus interface provides information about the status of an iteration. When you specify the varStatus attribute for <c:forEach> or <c:forTokens>, an object that implements the LoopTagStatus interface is made available in the body of those actions. You can use that object to obtain information about the current iteration.