Task

<forEach2>

An enhanced version of the <for> task of ant-contrib which supports <break> and <continue> subtasks.

It iterates over

• a list of strings, or
• a sequence of integers, starting with "1", or
• the elements of a resource collection, or
• the keys of a map, or
• the values of a map, or
• the elements of an Iterable, or
• an infinite sequence of integers, starting with "0" (the default if none of the above is configured),

and executes the configured <sequential> for each element. The behavior for the case that the Sequential fails is configured by the keepGoing attribute.

The dynamic attribute designated by param="..." reflects the value of the current element of the iteration.

Usage examples:

   <forEach2 list="a,b,c" param="s">
       <sequential>
           <echo message="@{s}" />
       </sequential>
   </forEach2>

   <forEach2 count=3 param="i">
       <sequential>
           <echo message="@{i}" />
       </sequential>
   </forEach2>
 

If the message="..." attribute is configured, the task reports the throughput of each iteration, and, if showEta="true", it computes and reports the estimated remaining time after each iteration. The messages that are logged before and after each element are the same as for the <throughput> task, however, the (previous|current|remaining)(Quantity|Duration) are not configured through properties, but reflect measured values:

previousQuantity	The number of elements processed before the current element, or, for resource collections, the total of the sizes of the resources processed before the current resource
previousDuration	The duration it took to process the elements before the current element
currentQuantity	1, or, for resource collections, the size of the current resource
currentDuration	The duration it took to process the current element

Attribute Summary

Attributes

Name	Description
count="..."	Iterate over the values "1", "2", "3", ...
currentBeginning="..."	Deprecated. For testing only
currentDuration="..."	Deprecated. For testing only
currentQuantity="..."	Deprecated. For testing only
delimiter="..."	Separates the elements within the list.
keepGoing="..."	Iff true, execution will not fail immediately if one of the subtasks fails.
list="..."	The elements to iterate are the given list, split at the configured delimiter.
message="..."	If set, then messages are logged before and after execution of the nested tasks (see the <throughput> task).
param="..."	The name of the dynamic attribute that refers to the current element.
quantityUnit="..."	Iff set, and message="..." is also set, then this is the 'unit' that the throughput will be reported in, e.g.
remainingBeginning="..."	Deprecated. For testing only
showEta="..."	Configures, together with message="...", the messages to be logged before and after execution of the nested tasks.
trim="..."	Whether the elements of the iteration, if they are strings, should silently be trimmed, i.e. leading and trailing whitespace be removed.

Subelement Summary

Subelements

Name	Description
<keysOf>	The elements to iterate are the keys of a java.util.Map.
<sequential>	Container for the subtasks to execute for each iteration.
<valuesOf>	The elements to iterate are the values of a java.util.Map.
Any ResourceCollection	The elements to iterate are the resources contained in this resource collection.
Any Iterable	The elements to iterate are those of this java.lang.Iterable.

Attribute Detail

Default values are underlined.

list="values"

The elements to iterate are the given list, split at the configured delimiter.

delimiter="delimiter-characters|,"

Separates the elements within the list.

trim="true|false"

Whether the elements of the iteration, if they are strings, should silently be trimmed, i.e. leading and trailing whitespace be removed.

count="n"

Iterate over the values "1", "2", "3", ... "N".

param="dynamic-attribute-name"

The name of the dynamic attribute that refers to the current element.

keepGoing="true|false"

Iff true, execution will not fail immediately if one of the subtasks fails. Instead, the iteration will continue with the following elements and execution will fail after the iteration is complete.

message="text"

If set, then messages are logged before and after execution of the nested tasks (see the <throughput> task).

Iff the iterated elements are resource collections, then the reported quantities are the sizes of the resources, and the quantity unit is "bytes", otherwise the quantities are the element counts, and the quantity unit is "elements".

quantityUnit="unit-name"

Iff set, and message="..." is also set, then this is the 'unit' that the throughput will be reported in, e.g. "bytes". If the related quantity is "1", then the quantity unit is automatically 'singularized', which means that a trailing 's' is chopped off.

The default is "elements"; for resources "bytes".

showEta="true|false"

Configures, together with message="...", the messages to be logged before and after execution of the nested tasks.

See also:

showEta="..."

currentBeginning="point-of-time"

Deprecated. For testing only

Use the given point-of-time as the "time of the beginning of the current interval" instead of the current time.

currentDuration="duration"

Deprecated. For testing only

Use the given duration as the "the duration of the current interval" instead of the real duration.

currentQuantity="n"

Deprecated. For testing only

Use the given values as the "quantity processed in the current interval" instead of the real quantity.

remainingBeginning="point-of-time"

Deprecated. For testing only

Use the given point-of-time as the "time of the beginning of the remaining interval" instead of the current time.

Subelement Detail

Any ResourceCollection

The elements to iterate are the resources contained in this resource collection.

For file resources, the param reflects the path of each file; for URL resources, it reflects the URL; for other resources (e.g. the elements of a <propertyset>), it reflects the name of each resource.

<keysOf>

The elements to iterate are the keys of a java.util.Map.

Subelements:

Any Map

The java.util.Map to use.

<valuesOf>

The elements to iterate are the values of a java.util.Map.

Subelements:

Any Map

The java.util.Map to use.

Any Iterable

The elements to iterate are those of this java.lang.Iterable.

<sequential>

Container for the subtasks to execute for each iteration.