[Index]

foreach


A job which executes its child jobs for each of the provided values. The child job can access the current value using the pseudo property 'current' to gain access to the current value. The pseudo property 'index' provides a 0 based number for the instance.

The return state of this job depends on the return state of the children (like sequential). Hard resetting this job will cause the children to be destroyed and recreated on the next run (with possibly new values). Soft resetting this job will reset the children but when re-run will not reconfigure the values.

As yet There is no persistence for child jobs.

It is not possible to reference the internal jobs via their id from outside the foreach job, but within the foreach internal configuration they can reference each other and themselves via their ids.


Property Summary

configuration The configuration that will be parsed for each value.
current The current value
executorService The ExecutorService to use.
file The name of the configuration file.
index The current index in the values.
loadable  
name A name, can be any text.
parallel Should jobs be executed in parallel.
preLoad The number of values to pre-load configurations for.
purgeAfter The number of completed jobs to keep.
stop Read only view of the internal stop flag.
values Any value.

Example Summary

Example 1 For each of 3 values.
Example 2 For each of 3 files.
Example 3 Executing children in parallel.
Example 4 Using an execution window.

Property Detail

configuration

Configured ByELEMENT
AccessREAD_WRITE
RequiredYes.

The configuration that will be parsed for each value.

current

AccessREAD_ONLY
RequiredR/O.

The current value

executorService

Configured ByELEMENT
AccessWRITE_ONLY
RequiredNo.

The ExecutorService to use. This will be automatically set by Oddjob.

file

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo.

The name of the configuration file. to use for configuration.

index

AccessREAD_ONLY
RequiredR/O.

The current index in the values.

loadable

AccessREAD_ONLY

name

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo.

A name, can be any text.

parallel

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo. Defaults to false.

Should jobs be executed in parallel.

preLoad

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo. Defaults to all configurations being loaded first.

The number of values to pre-load configurations for. This property can be used with large sets of values to ensure that only a certain number are pre-loaded before execution starts.

This property won't work correctly when parallel is true.

purgeAfter

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo. Defaults to no complete jobs being purged.

The number of completed jobs to keep. Oddjob configurations can be quite memory intensive, mainly due to logging, purging complete jobs will stop too much memory being taken.

This property won't work correctly when parallel is true.

stop

AccessREAD_ONLY
RequiredRead only.

Read only view of the internal stop flag. This flag is cleared with a reset.

values

Configured ByELEMENT
AccessWRITE_ONLY
RequiredNo.

Any value.


Examples

Example 1

For each of 3 values.

<oddjob id="this" xmlns:arooa="http://rgordon.co.uk/oddjob/arooa">
    <job>
        <foreach id="foreach">
            <values>
                <list>
                    <values>
                        <value value="Red"/>
                        <value value="Blue"/>
                        <value value="Green"/>
                    </values>
                </list>
            </values>
            <configuration>
                <arooa:configuration resource="org/oddjob/jobs/structural/ForEachEchoColour.xml"/>
            </configuration>
        </foreach>
    </job>
</oddjob>
The internal configuration is:
<foreach id="colours">
    <job>
        <echo id="echo-colour" name="${colours.current}">I'm number ${colours.index} and my name is ${echo-colour.name}</echo>
    </job>
</foreach>
Unlike other jobs, a job in a for each has it's name configured when it is loaded, before it is run. The job references its self using its id.

This example will display the following on the console:

 I'm number 0 and my name is Red
 I'm number 1 and my name is Blue
 I'm number 2 and my name is Green
 

Example 2

For each of 3 files. The 3 files test1.txt, test2.txt and test3.txt are copied to the work/foreach directory. The oddjob argument ${this.args[0]} is so that a base directory can be passed in as part of the unit test for this example.

<oddjob id="this" xmlns:arooa="http://rgordon.co.uk/oddjob/arooa">
    <job>
        <foreach>
            <values>
                <files files="${this.args[0]}/test/io/reference/test?.txt"/>
            </values>
            <configuration>
                <arooa:configuration>
                    <xml>
                        <xml>
                            <foreach id="copy-files">
                                <job>
                                    <copy to="${this.args[0]}/work/foreach">
                                        <from>
                                            <value value="${copy-files.current}"/>
                                        </from>
                                    </copy>
                                </job>
                            </foreach>
                        </xml>
                    </xml>
                </arooa:configuration>
            </configuration>
        </foreach>
    </job>
</oddjob>
Also exists has a similar example.

Example 3

Executing children in parallel. This example uses a throttle to limit the number of parallel executions to three.

<oddjob>
    <job>
        <foreach parallel="true">
            <values>
                <tokenizer text="1,2,3,4,5,6,7,8,9"/>
            </values>
            <configuration>
                <xml>
                    <foreach id="loop">
                        <job>
                            <wait name="Wait ${loop.current}"/>
                        </job>
                    </foreach>
                </xml>
            </configuration>
            <executorService>
                <throttle limit="3"/>
            </executorService>
        </foreach>
    </job>
</oddjob>

Example 4

Using an execution window. Only the configuration for two jobs will be pre-loaded, and only the last three complete jobs will remain loaded.

<oddjob id="this">
    <job>
        <foreach preLoad="2" purgeAfter="3">
            <values>
                <tokenizer text="1,2,3,4,5,6,7,8,9,10,11,12,13,14,15"/>
            </values>
            <configuration>
                <xml>
                    <foreach id="loop">
                        <job>
                            <wait name="Wait ${loop.current} " pause="1"/>
                        </job>
                    </foreach>
                </xml>
            </configuration>
        </foreach>
    </job>
</oddjob>


(c) Rob Gordon 2005 - 2013