org.oddjob.jobs.structural
Class ForEachJob

java.lang.Object
  extended by org.oddjob.framework.BaseComponent
      extended by org.oddjob.framework.BasePrimary
          extended by org.oddjob.framework.StructuralJob<Runnable>
              extended by org.oddjob.jobs.structural.ForEachJob
All Implemented Interfaces:
Serializable, Runnable, ArooaContextAware, ArooaSessionAware, 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
 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()
           
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()
           
 void load()
          Load the component.
protected  Runnable 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()
          Setup and load the first jobs.
 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, isStop, 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.

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<Runnable>
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. 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. If this is null the Oddjob Explorer won't show a DesignInside action.

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 ConfiguraitonSession is available.

loadConfigFor

protected Runnable loadConfigFor(Object value)
                          throws ArooaParseException
Load a configuration for a single value.

Parameters:
value -
Throws:
ArooaParseException

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