org.oddjob.jobs.structural

Class ForEachJob

java.lang.Object

org.oddjob.framework.extend.BaseComponent

org.oddjob.framework.extend.BasePrimary

org.oddjob.framework.extend.StructuralJob<java.lang.Object>

org.oddjob.jobs.structural.ForEachJob

All Implemented Interfaces:

java.io.Serializable, java.lang.Runnable, ArooaContextAware, ArooaSessionAware, ConfigurationOwner, BeanDirectoryOwner, Forceable, PropertyChangeNotifier, Iconic, Loadable, LogEnabled, Resettable, Stateful, Stoppable, Structural

public class ForEachJob
extends StructuralJob<java.lang.Object>
implements Stoppable, Loadable, ConfigurationOwner, BeanDirectoryOwner

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="${base.dir}/test/io/reference/test?.txt"/>
            </values>
            <configuration>
                <arooa:configuration>
                    <xml>
                        <xml>
                            <foreach id="copy-files">
                                <job>
                                    <copy to="${some.dir}">
                                        <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

Nested Classes

Modifier and Type	Class and Description
class	ForEachJob.LocalBean This provides a bean for current properties.

Field Summary

Fields

Modifier and Type	Field and Description
static ArooaElement	FOREACH_ELEMENT Root element for configuration.

Fields inherited from class org.oddjob.framework.extend.StructuralJob

childHelper, destroy, stop, structuralState

Constructor Summary

Constructors

Constructor and Description
ForEachJob() Constructor.

Method Summary

Modifier and Type	Method and Description
void	addOwnerStateListener(OwnerStateListener listener) Add a listener.
protected void	execute() Execute this job.
ArooaConfiguration	getConfiguration()
java.lang.Object	getCurrent() The current value.
java.util.concurrent.ExecutorService	getExecutorService()
java.io.File	getFile()
int	getIndex()
protected StateOperator	getInitialStateOp() Subclasses must provide the StateOperator that will decide how to evaluate the children's state.
int	getPreLoad()
int	getPurgeAfter()
boolean	hardReset() Perform a hard reset on the job.
boolean	isLoadable() Is the component currently loadable.
boolean	isParallel()
boolean	isStop() Expose the internal stop flag as a read only property.
void	load() Load the component.
protected java.lang.Object	loadConfigFor(java.lang.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() Setup and load the first jobs.
BeanDirectory	provideBeanDirectory() Get the BeanDirectory.
ConfigurationSession	provideConfigurationSession() Provide a ConfigurationSession.
void	removeOwnerStateListener(OwnerStateListener listener) Remove a listener.
SerializableDesignFactory	rootDesignFactory() Get the design factory for the configuration.
ArooaElement	rootElement() Get the root element.
void	setConfiguration(ArooaConfiguration configuration)
void	setExecutorService(java.util.concurrent.ExecutorService executorService) Set the ExecutorService.
void	setFile(java.io.File file)
void	setParallel(boolean parallel)
void	setPreLoad(int preLoad)
void	setPurgeAfter(int purgeAfter)
void	setValues(java.lang.Iterable<?> values) Set the values to iterate over.
protected void	startChildStateReflector() Start the child state reflector.
void	unload() Unload the component.

Methods inherited from class org.oddjob.framework.extend.StructuralJob

addStructuralListener, fireDestroyedState, force, getStateChanger, iconHelper, onHardReset, onReset, onSoftReset, postStop, removeStructuralListener, run, softReset, stateHandler, stop, stopChildStateReflector, waitForChildrenOnStop

Methods inherited from class org.oddjob.framework.extend.BasePrimary

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

Methods inherited from class org.oddjob.framework.extend.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(java.util.concurrent.ExecutorService executorService)

Set the ExecutorService.

Property: executorService

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

Required: No.

Parameters:

executorService - The Executor Service.

getExecutorService

public java.util.concurrent.ExecutorService getExecutorService()

getCurrent

public java.lang.Object getCurrent()

The current value.

Returns:

The current value.

setValues

public void setValues(java.lang.Iterable<?> values)

Set the values to iterate over.

Parameters:

values - The values.

getInitialStateOp

protected StateOperator getInitialStateOp()

Description copied from class: StructuralJob

Subclasses must provide the StateOperator that will decide how to evaluate the children's state.

Specified by:

getInitialStateOp in class StructuralJob<java.lang.Object>

Returns:

A State Operator. Must not be null.

provideConfigurationSession

public ConfigurationSession provideConfigurationSession()

Description copied from interface: ConfigurationOwner

Provide a ConfigurationSession.

Specified by:

provideConfigurationSession in interface ConfigurationOwner

Returns:

A ConfigurationSession. May 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 SerializableDesignFactory rootDesignFactory()

Description copied from interface: ConfigurationOwner

Get the design factory for the configuration. If this is null the Oddjob Explorer won't show a DesignInside action.

Note that this is a SerializableDesignFactory so that this interface can be represented remotely.

Specified by:

rootDesignFactory in interface ConfigurationOwner

Returns:

A DesignFactory. Must not be null if a ConfigurationSession is available.

rootElement

public ArooaElement rootElement()

Description copied from interface: ConfigurationOwner

Get the root element.

Specified by:

rootElement in interface ConfigurationOwner

Returns:

The root element of the configuration. Must not be null if a ConfigurationSession is available.

loadConfigFor

protected java.lang.Object loadConfigFor(java.lang.Object value)
                                  throws ArooaParseException

Load a configuration for a single value.

Parameters:

value - The value

Returns:

The root component in the child configuration.

Throws:

ArooaParseException - If the config can't be parsed.

provideBeanDirectory

public BeanDirectory provideBeanDirectory()

Description copied from interface: BeanDirectoryOwner

Get the BeanDirectory. This method may return null if the BeanDirectory isn't available.

Specified by:

provideBeanDirectory in interface BeanDirectoryOwner

Returns:

The BeanDirectory or null.

preLoad

protected void preLoad()
                throws ArooaParseException

Setup and load the first jobs.

if preLoad is 0 all will be loaded otherwise up to that number will be loaded.

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 java.lang.Exception

Description copied from class: StructuralJob

Execute this job.

Specified by:

execute in class StructuralJob<java.lang.Object>

Throws:

java.lang.Exception - If the unexpected occurs.

startChildStateReflector

protected void startChildStateReflector()

Description copied from class: StructuralJob

Start the child state reflector. Sub classes override this if they need to start the child state reflector at a different time.

Overrides:

startChildStateReflector in class StructuralJob<java.lang.Object>

onStop

protected void onStop()
               throws FailedToStopException

Description copied from class: StructuralJob

Allow sub classes to do something on stop.

Overrides:

onStop in class StructuralJob<java.lang.Object>

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. This is called by the framework before child elements have been destroyed.

Overrides:

onDestroy in class StructuralJob<java.lang.Object>

hardReset

public boolean hardReset()

Perform a hard reset on the job.

Specified by:

hardReset in interface Resettable

Overrides:

hardReset in class StructuralJob<java.lang.Object>

Returns:

true if successful.

isStop

public boolean isStop()

Description copied from class: StructuralJob

Expose the internal stop flag as a read only property.

Overrides:

isStop in class StructuralJob<java.lang.Object>

Property: stop

Description: The stop flag. This is an internal read only property that is exposed for diagnostic reasons. If a child job does not support stopping then the request to stop may time out but it is useful to know that the stop flag is still set so this job will still stop eventually.

Required: Read Only.

Returns:

The file name.

setFile

public void setFile(java.io.File file)

Property: file

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

Required: No.

getFile

public java.io.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)