11.10 XML Flow Control Actions

The XML flow control actions mimic the flow control actions from the JSTL Core library, except that the XML flow control actions operate on XPath expressions instead of EL expressions. See "General-Purpose Actions" on page 469, and see "Conditional Actions" on page 474 for more information about the corresponding actions from the Core library.

Table 11.24 lists the XML flow control actions. For each of the actions listed in Table 11.24, there is a corresponding action from the Core library.

Table 11.24. XML Flow Control Actions

Action	Description
<x:if>	Represents a simple conditional statement depending on whether an XPath expression is true or false.
<x:choose>	Sets the context for mutually exclusive conditional statements ”meaning that <x:choose> actions can only contain <x:when> and <x: otherwise > actions that choose one of several alternatives depending on whether an XPath expression is true or false.
<x:when>	Represents one alternative in the body of an <x:choose> action.
<x:otherwise>	Represents the default alternative in the body of an <x:choose> action.
<x:forEach>	Iterates over a set of nodes returned from an XPath expression.

<x:if>

Evaluates its body content if a specified XPath expression is true

Syntax: ^[32]

^[32] Items in brackets are optional.

Syntax #1: Without a body, stores the test result in a scoped variable

 <x:if select var [scope]/> 

Syntax #2: With a body that's evaluated if the test condition is true.

 <x:if select [var] [scope]>  body content  </x:if> 

Description:

The <x:if> action evaluates an XPath expression and coerces the result to a boolean value. If that value is true , the <x:if> action evaluates its body content, if present; if not, the body content is ignored. You can also store the boolean result of that expression in a scoped variable that you specify with the var attribute, and optionally , the scope attribute. The <c:if> action works the same way, except that you specify an EL expression instead of an XPath expression.

Attributes:

Attribute [a]	Type	Description
select	String	An XPath expression that <x:if> coerces to a boolean value. If that value is true , the <x:if> action evaluates its body content; if not, the body content is ignored.
var	String	A scoped variable that stores the boolean result of the XPath expression specified with the select attribute.
scope	String	The scope of the scoped variable whose name is specified by the var attribute; default is page scope.

^[a] static dynamic

Constraints and Error Handling:

• If you specify the scope attribute, you must also specify the var attribute.

In a Nutshell:

As with the <c:if> action, you can store the result of the expression in a scoped variable. You specify the name of that scoped variable with the var attribute and its scope with the scope attribute.

<x:choose>

Provides a context for <x:when> and <x:choose>

Syntax:

 <x:choose>  nested <x:when> actions and an optional <x:otherwise> action  </x:choose> 

Description:

The <x:choose> action provides a context for mutually exclusive conditions. The body of this action can only contain whitespace, one or more nested <x:when> actions, and an optional <x:otherwise> action.

Attributes: none

Constraints and Error Handling:

• The body of an <x:choose> action can only contain whitespace, one or more <x:when> actions, and an optional <x:otherwise> action. The <x:otherwise> action, if present, must be the last action in the body of the <x:choose> action.

In a Nutshell:

The body of an <x:choose> action can contain multiple <x:when> actions and an optional <x:otherwise> action. The body content of the first <x:when> action whose select attribute represents a true XPath expression is evaluated, and the other <x:when> actions and optional <x:otherwise> action are ignored. If none of the <x:when> actions have a true XPath expression, the body content of the optional <x:otherwise> action, if present, is evaluated.

<x:when>

An alternative in a <x:choose> action

Syntax:

 <x:when select>  body content  </x:when> 

Description:

The body content of an <x:when> action is evaluated if that action's XPath expression ”specified with the select attribute ”is true and the action is the first <x:when> action ”contained in an <x:choose> action ”whose XPath expression evaluates to true.

Attributes:

Attribute [a]	Type	Description
select	String	An XPath expression.

^[a] static dynamic

Constraints and Error Handling:

• All <x:when> actions must reside in the body of an <x:choose> action.

• All <x:when> actions must appear before the <x:otherwise> action, if present.

In a Nutshell:

You specify an XPath expression with the select attribute, which <x:when> coerces to a boolean value. If that value is true and the <x:when> action is the first <x:when> action whose XPath expression evaluates to true , its body content is evaluated.

<x:otherwise>

The alternative if no <x:when> actions in the same <x:choose> have true XPath expressions

Syntax:

 <x:otherwise>  body content  </x:otherwise> 

Description:

The body content of an <x:otherwise> action is evaluated only if none of the preceding <x:when> actions contained in the same <x:choose> action evaluated to true . The action:default behavior]><x:otherwise> action, like the <c:otherwise> action, represents default behavior for mutually exclusive conditional statements.

Attributes: none

Constraints and Error Handling:

• An action:constraints]><x:otherwise> action must reside in the body of an <x:choose> action and must be the last action contained in the body of that <x:choose> action.

<x:forEach>

Iterates over a node-set returned from an XPath expression

Syntax: ^[33]

^[33] Items in brackets are optional.

 <x:forEach select [var]>  body content  </x:forEach> 

Description:

The <x:forEach> action iterates over a node-set returned from an XPath expression. The body content of the <x:forEach> action is evaluated for every node in the node-set.

Attributes:

Attribute [a]	Type	Description
select	String	An XPath expression.
var	String	The name of the scoped variable representing the current item of the iteration.

^[a] static dynamic

Constraints and Error Handling:

• If the XPath expression specified with the select attribute is null or an empty string, <x:forEach> will throw a JspException .

In a Nutshell:

Like <c:forEach>, the <x:forEach> action iterates over a collection of objects. For <x:forEach>, that collection is a node-set that is the result of an XPath expression.

The <x:forEach> action is a poor cousin of the <c:forEach> action. The latter offers six attributes and numerous amenities such as iterating over a range of items in a collection, iterating over integer values, and accessing a status variable. The <x:forEach> action, by contrast, offers only two attributes and none of the amenities listed above that are provided by the <c:forEach> action.

It's important to understand that <x:forEach> sets the context node for XPath expressions inside its body content; for example, the following code fragment iterates over nodes from an XML Rolodex:

 <x:forEach select='$document//contact'>     <table>       <tr>          <td>First Name:</td>          <td><x:out  select='firstName'  /></td>       </tr>       <tr>          <td>Last Name:</td>          <td><x:out  select='lastName'  /></td>       </tr>       <tr>          <td>Email:</td>          <td><x:out  select='email'  /></td>       </tr>       <tr>          <td>Work Phone:</td>          <td><x:out  select='phone[@type="work"]'  /></td>       </tr>    </table> </x:forEach> 

In the preceding code fragment, every time the <x:forEach> action iterates over its body, it resets the context node. This feature simplifies XPath expressions within the body of <x:forEach> because they don't have to specify an absolute path . Because <x:forEach> sets the context node, the need to specify the var attribute, which specifies the name of a scoped variable that refers to the current item of the iteration, is greatly diminished.