org.oddjob.jobs.structural
Class ForEachJob

java.lang.Object
  org.oddjob.framework.BaseComponent
      org.oddjob.framework.BasePrimary
          org.oddjob.framework.StructuralJob<Runnable>
              org.oddjob.jobs.structural.ForEachJob

All Implemented Interfaces:

Serializable, Runnable, ArooaContextAware, ConfigurationOwner, Forceable, PropertyChangeNotifier, Iconic, Loadable, LogEnabled, Resetable, Stateful, Stoppable, Structural

public class ForEachJob
extends StructuralJob<Runnable>
implements Stoppable, Loadable, ConfigurationOwner

Description

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 SequentialJob). 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.

Example

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

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 ExistsJob has a similar example.

Example

Executing children in parallel. This example uses a ExecutorThrottleType 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

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>

See Also:

Serialized Form

Nested Class Summary

static class

ForEachJob.LocalBean This provides a bean for current properties.

Field Summary

static ArooaElement

FOREACH_ELEMENT Root element for configuration.

Fields inherited from class org.oddjob.framework.StructuralJob

childHelper, childStateReflector, stateHandler, stop, structuralState

Fields inherited from class org.oddjob.framework.BaseComponent

iconHelper

Constructor Summary

ForEachJob()
Constructor.

Method Summary

void	addOwnerStateListener(OwnerStateListener listener) Add a listener.
protected void	execute() Execute this job.
ArooaConfiguration	getConfiguration()
Object	getCurrent() The current value.
File	getFile()
int	getIndex()
int	getPreLoad()
int	getPurgeAfter()
protected StateOperator	getStateOp()
boolean	hardReset() Perform a hard reset on the job.
boolean	isLoadable() Is the component currently loadable.
boolean	isParallel()
void	load() Load the component.
protected void	loadConfigFor(Object value) Load a configuration for a single value.
protected void	onDestroy() Subclasses override this method to clear up resources.
protected void	onStop() Allow sub classes to do something on stop.
protected void	preLoad()
ConfigurationSession	provideConfigurationSession() Provide a ConfigurationSession.
void	removeOwnerStateListener(OwnerStateListener listener) Remove a listener.
DesignFactory	rootDesignFactory() Get the design factory for the configuration.
ArooaElement	rootElement() Get the root element.
void	setConfiguration(ArooaConfiguration configuration)
void	setExecutorService(ExecutorService executorService) Set the ExecutorService.
void	setFile(File file)
void	setParallel(boolean parallel)
void	setPreLoad(int preLoad)
void	setPurgeAfter(int purgeAfter)
void	setValues(Iterable<? extends Object> values) Add a type.
protected void	startChildStateReflector()
void	unload() Unload the component.

Methods inherited from class org.oddjob.framework.StructuralJob

addStructuralListener, fireDestroyedState, force, getStateChanger, onReset, removeStructuralListener, run, softReset, stateHandler, stop

Methods inherited from class org.oddjob.framework.BasePrimary

configure, getName, logger, logger, loggerName, save, setName, toString

Methods inherited from class org.oddjob.framework.BaseComponent

addIconListener, addPropertyChangeListener, addStateListener, configure, destroy, firePropertyChange, getArooaSession, iconForId, initialise, lastStateEvent, onConfigured, onInitialised, removeIconListener, removePropertyChangeListener, removeStateListener, save, setArooaContext, setArooaSession

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.oddjob.Stoppable

stop

Methods inherited from interface org.oddjob.Stateful

addStateListener, lastStateEvent, removeStateListener

Field Detail

FOREACH_ELEMENT

public static final ArooaElement FOREACH_ELEMENT

Root element for configuration.

Constructor Detail

ForEachJob

public ForEachJob()

Constructor.

Method Detail

setExecutorService

@Inject
public void setExecutorService(ExecutorService executorService)

Set the ExecutorService.

Property: executorService

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

Required: No.

Parameters:

child - A child

getCurrent

public Object getCurrent()

The current value.

Returns:

The current value.

setValues

public void setValues(Iterable<? extends Object> values)

Add a type. This will be called during parsing by the handler to add a type for each element.

Parameters:

type - The type.

getStateOp

protected StateOperator getStateOp()

Specified by:

getStateOp in class StructuralJob<Runnable>

provideConfigurationSession

public ConfigurationSession provideConfigurationSession()

Description copied from interface: ConfigurationOwner

Provide a ConfigurationSession.

Specified by:

provideConfigurationSession in interface ConfigurationOwner

Returns:

A ConfigurationSession. My be null if no session is available.

addOwnerStateListener

public void addOwnerStateListener(OwnerStateListener listener)

Description copied from interface: ConfigurationOwner

Add a listener.

Specified by:

addOwnerStateListener in interface ConfigurationOwner

removeOwnerStateListener

public void removeOwnerStateListener(OwnerStateListener listener)

Description copied from interface: ConfigurationOwner

Remove a listener.

Specified by:

removeOwnerStateListener in interface ConfigurationOwner

rootDesignFactory

public DesignFactory rootDesignFactory()

Description copied from interface: ConfigurationOwner

Get the design factory for the configuration.

Specified by:

rootDesignFactory in interface ConfigurationOwner

Returns:

Never null.

rootElement

public ArooaElement rootElement()

Description copied from interface: ConfigurationOwner

Get the root element.

Specified by:

rootElement in interface ConfigurationOwner

Returns:

Never null.

loadConfigFor

protected void loadConfigFor(Object value)
                      throws ArooaParseException

Load a configuration for a single value.

Parameters:

value -

Throws:

ArooaParseException

preLoad

protected void preLoad()
                throws ArooaParseException

Throws:

ArooaParseException

load

public void load()

Description copied from interface: Loadable

Load the component.

Specified by:

load in interface Loadable

unload

public void unload()

Description copied from interface: Loadable

Unload the component.

Specified by:

unload in interface Loadable

isLoadable

public boolean isLoadable()

Description copied from interface: Loadable

Is the component currently loadable.

Specified by:

isLoadable in interface Loadable

Returns:

true if the component can be loaded, false otherwise.

execute

protected void execute()
                throws Exception

Description copied from class: StructuralJob

Execute this job.

Specified by:

execute in class StructuralJob<Runnable>

Throws:

Exception - If the unexpected occurs.

startChildStateReflector

protected void startChildStateReflector()

Overrides:

startChildStateReflector in class StructuralJob<Runnable>

onStop

protected void onStop()
               throws FailedToStopException

Description copied from class: StructuralJob

Allow sub classes to do something on stop.

Overrides:

onStop in class StructuralJob<Runnable>

Throws:

FailedToStopException

getIndex

public int getIndex()

Returns:

Returns the index.

onDestroy

protected void onDestroy()

Description copied from class: BaseComponent

Subclasses override this method to clear up resources.

Overrides:

onDestroy in class StructuralJob<Runnable>

hardReset

public boolean hardReset()

Perform a hard reset on the job.

Specified by:

hardReset in interface Resetable

Overrides:

hardReset in class StructuralJob<Runnable>

Returns:

true if successful.

setFile

public void setFile(File file)

Property: file

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

Required: No.

getFile

public File getFile()

getConfiguration

public ArooaConfiguration getConfiguration()

setConfiguration

public void setConfiguration(ArooaConfiguration configuration)

getPreLoad

public int getPreLoad()

setPreLoad

public void setPreLoad(int preLoad)

getPurgeAfter

public int getPurgeAfter()

setPurgeAfter

public void setPurgeAfter(int purgeAfter)

isParallel

public boolean isParallel()

setParallel

public void setParallel(boolean parallel)