org.oddjob
Class Oddjob

java.lang.Object
  extended by org.oddjob.framework.BaseComponent
      extended by org.oddjob.framework.BasePrimary
          extended by org.oddjob.framework.StructuralJob<Object>
              extended by org.oddjob.Oddjob
All Implemented Interfaces:
Serializable, Runnable, ArooaContextAware, ArooaSessionAware, ConfigurationOwner, BeanDirectoryOwner, Forceable, PropertyChangeNotifier, Iconic, Loadable, LogEnabled, Resetable, Stateful, Stoppable, Structural

public class Oddjob
extends StructuralJob<Object>
implements Loadable, ConfigurationOwner, BeanDirectoryOwner

Read a configuration, creates child jobs and executes them.

Description

The starting point for a hierarchy of jobs. The Oddjob job creates and runs a job hierarchy by processing a supplied configuration.

Oddjob creates a 'root' job on which to create the hierarchy. Through this root Oddjob aquires the first job to run and also exposes some of it's own properties for the jobs in the configuration to use. The root job's properties are:

job
The top level job. This is the single job that Oddjob runs. This property is optional but Oddjob won't do much if a job for it to run isn't supplied. This is the Oddjob root's only writeable property and is write only.
file
The path of the configuration file that Oddjob has loaded. Read Only.
dir
The path of the configuration file's directory. Read Only.
args
An array of arguments passed in on the command line or from a parent Oddjob. See below. Read Only.
services
Provides access to Oddjobs underlying services. Used by the frameworks automatic configuration mechanism to configure the properties of jobs that are documented as set automatically. May be ignored for every day use. Read Only.

For these properties to be accessible the root oddjob must be given an id. As can be seen from the examples, the author uses the id 'this' but the choice is arbitrary.

Nesting Oddjobs

An Oddjob job allows an Oddjob instance to be created within an existing Oddjob configuration. This way complicated processes can be created in manageable and separately testable units.

Properties of jobs in a nested Oddjob can be accessed using the notation ${nested-oddjob-id/job-id.property} where nested-oddjob-id is the id in the outer configuration, not the inner one.

Saving Oddjob's State

The persister property on a nested Oddjob will allow it's state to be saved. See the User Guide for more information on how to set a persister.

Customising Oddjob

Oddjob's descriptorFactory and classLoader properties allow bespoke components and types to be used. The developer guide is all about writing custom job's for Oddjob.

Example

Hello World with Oddjob. Oddjob is configured to run the EchoJob job.
<oddjob>
    <job>
        <echo id="echo">Hello World</echo>
    </job>
</oddjob>

Example

Using an argument passed into Oddjob that may or may not be set.
<oddjob id="this">
    <job>
        <sequential>
            <jobs>
                <state:if xmlns:state="http://rgordon.co.uk/oddjob/state">
                    <jobs>
                        <check value="${this.args[0]}"/>
                        <properties>
                            <values>
                                <value key="our.file.name" value="${this.args[0]}"/>
                            </values>
                        </properties>
                        <input>
                            <requests>
                                <input-text prompt="File Name?" property="our.file.name"/>
                            </requests>
                        </input>
                    </jobs>
                </state:if>
                <echo>File Name is ${our.file.name}</echo>
            </jobs>
        </sequential>
    </job>
</oddjob>

Example

Nesting Oddjob. Note how the dir property of the Oddjob root is used as the path of the nested configuration file.
<oddjob id="this">
    <job>
        <sequential>
            <jobs>
                <oddjob id="nested" file="${this.dir}/HelloWorld.xml"/>
                <echo>Nested job said: ${nested/echo.text}</echo>
            </jobs>
        </sequential>
    </job>
</oddjob>

The nested job is the first example:

<oddjob>
    <job>
        <echo id="echo">Hello World</echo>
    </job>
</oddjob>
This example also shows how a property within the nested file can be accessed within the parent configuration.

Example

A nested Oddjob with one argument passed to the child.
<oddjob id="this">
    <job>
        <oddjob id="nested" file="${this.dir}/EchoArg.xml">
            <args>
                <list>
                    <values>
                        <value value="Hello World"/>
                    </values>
                </list>
            </args>
        </oddjob>
    </job>
</oddjob>
And EchoArg.xml:
<oddjob id="this">
    <job>
        <echo id="echo">${this.args[0]}</echo>
    </job>
</oddjob>

Example

A nested Oddjob with a property past to the child.
<oddjob id="this">
    <job>
        <oddjob id="nested" file="${this.dir}/EchoProperty.xml">
            <properties>
                <properties>
                    <values>
                        <value key="our.greeting" value="Hello World"/>
                    </values>
                </properties>
            </properties>
        </oddjob>
    </job>
</oddjob>
And EchoProperty.xml:
<oddjob id="this">
    <job>
        <echo id="echo">${our.greeting}</echo>
    </job>
</oddjob>
Unlike the properties of jobs, free format properties like this can't be accessed using the nested convention.
 ${nested/our.greeting} DOES NOT WORK!
 
This may be fixed in future versions.

Example

Using export to pass values to a nested Oddjob.
<oddjob>
    <job>
        <sequential>
            <jobs>
                <folder>
                    <jobs>
                        <echo id="secret">I'm a secret job</echo>
                    </jobs>
                </folder>
                <oddjob id="inner">
                    <export>
                        <value key="secret" value="${secret}"/>
                    </export>
                    <configuration>
                        <arooa:configuration xmlns:arooa="http://rgordon.co.uk/oddjob/arooa">
                            <xml>
                                <xml>
                                    <oddjob>
                                        <job>
                                            <run job="${secret}"/>
                                        </job>
                                    </oddjob>
                                </xml>
                            </xml>
                        </arooa:configuration>
                    </configuration>
                </oddjob>
            </jobs>
        </sequential>
    </job>
</oddjob>
Here a job is exported into a nested Oddjob. The exported object is actually a ValueType. The value is converted back to the job when the job property of the run job is set. Expressions such as ${secret.text} are not valid (because value does not have a text property!). Even ${secret.value.text} will not work because of value wraps the job in yet another layer of complexity.

Example

Examples elsewhere.

See Also:
Serialized Form
Author:
Rob Gordon

Nested Class Summary
 class Oddjob.OddjobRoot
          The object which is the Oddjob root.
static class Oddjob.OddjobRootArooa
          Provide an ArooaBeanDescriptor for the root Oddjob bean.
 
Field Summary
static LogArchive CONSOLE
          The archiver to which all console output will be captured.
static ArooaElement ODDJOB_ELEMENT
          The document root for an Oddjob configuration file.
static String VERSION
          Oddjob version.
 
Fields inherited from class org.oddjob.framework.StructuralJob
childHelper, childStateReflector, stateHandler, stop, structuralState
 
Fields inherited from class org.oddjob.framework.BaseComponent
iconHelper
 
Constructor Summary
Oddjob()
          Only constructor.
 
Method Summary
 void addOwnerStateListener(OwnerStateListener listener)
          Add a listener.
protected  void execute()
          Execute this job.
 String[] getArgs()
           
 ClassLoader getClassLoader()
          Return a class loader.
 ArooaDescriptorFactory getDescriptorFactory()
          Getter.
 File getDir()
           
 ArooaValue getExport(String key)
          Getter
 File getFile()
           
 OddjobInheritance getInheritance()
          Getter.
protected  StateOperator getInitialStateOp()
          Subclasses must provide the StateOperator that will decide how to evaluate the children's state.
 InputHandler getInputHandler()
          Getter.
 org.oddjob.Oddjob.Reset getLastReset()
          Getter for last reset.
 OddjobExecutors getOddjobExecutors()
          Getter for OddjobExecutors that have been given to this instance of Oddjob.
 OddjobServices getOddjobServices()
          Getter for OddjobServices.
 OddjobPersister getPersister()
           
 Properties getProperties()
          Getter.
 String getVersion()
           
 boolean hardReset()
          Perform a hard reset.
 boolean isLoadable()
          Is the component currently loadable.
 void load()
          Load the component.
protected  void onDestroy()
          Subclasses override this method to clear up resources.
 BeanDirectory provideBeanDirectory()
          Get the BeanDirectory.
 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 setArgs(String[] args)
           
 void setClassLoader(ClassLoader classLoader)
           
 void setConfiguration(ArooaConfiguration config)
          Setter for configuration.
 void setDescriptorFactory(ArooaDescriptorFactory descriptorFactory)
          Setter.
 void setExport(String key, ArooaValue value)
          Setter.
 void setFile(File file)
           
 void setInheritance(OddjobInheritance inheritance)
          Setter.
 void setInputHandler(InputHandler inputHandler)
          Setter.
 void setOddjobExecutors(OddjobExecutors executors)
          Setter.
 void setOddjobServices(OddjobServices oddjobServices)
          Allow for injection of OddjobServices
 void setPersister(OddjobPersister persister)
           
 void setProperties(Properties properties)
          Setter.
 boolean softReset()
          Perform a soft reset on the job.
 String toString()
          Override toString.
 void unload()
          Unload the component.
 
Methods inherited from class org.oddjob.framework.StructuralJob
addStructuralListener, fireDestroyedState, force, getStateChanger, isStop, onReset, onStop, removeStructuralListener, run, startChildStateReflector, stateHandler, stop
 
Methods inherited from class org.oddjob.framework.BasePrimary
configure, getName, logger, logger, loggerName, save, setName
 
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.Stateful
addStateListener, lastStateEvent, removeStateListener
 

Field Detail

VERSION

public static final String VERSION
Oddjob version. Set by Ant during build.

See Also:
Constant Field Values

CONSOLE

public static final LogArchive CONSOLE
The archiver to which all console output will be captured.


ODDJOB_ELEMENT

public static final ArooaElement ODDJOB_ELEMENT
The document root for an Oddjob configuration file.

Constructor Detail

Oddjob

public Oddjob()
Only constructor.

Method Detail

setFile

public void setFile(File file)

Property: file

Description: The name of the configuration file. to configure this oddjob.

Required: No.


getFile

public File getFile()

setConfiguration

public void setConfiguration(ArooaConfiguration config)
Setter for configuration.

Parameters:
config -

setClassLoader

public void setClassLoader(ClassLoader classLoader)

Property: classLoader

Description: The classLoader to use when loading the configuration.

See also URLClassLoaderType

Required: No.


getClassLoader

public ClassLoader getClassLoader()
Return a class loader. If one has not been set return the class loader which loaded this class.

Returns:
A classLoader.

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.

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<Object>
Returns:
A State Operator. Must not be null.

isLoadable

public boolean isLoadable()
Description copied from interface: Loadable
Is the component currently loadable.

Specified by:
isLoadable in interface Loadable

Property: loadable

Description: Can Oddjob be loaded. Used by the Load/Unload actions.

Required: Read only.

Returns:
true if the component can be loaded, false otherwise.

load

public void load()
Description copied from interface: Loadable
Load the component.

Specified by:
load in interface Loadable

execute

protected void execute()
                throws Exception
Description copied from class: StructuralJob
Execute this job.

Specified by:
execute in class StructuralJob<Object>
Throws:
Exception - If the unexpected occurs.

unload

public void unload()
Description copied from interface: Loadable
Unload the component.

Specified by:
unload in interface Loadable

onDestroy

protected void onDestroy()
Description copied from class: BaseComponent
Subclasses override this method to clear up resources.

Overrides:
onDestroy in class StructuralJob<Object>

softReset

public boolean softReset()
Description copied from class: StructuralJob
Perform a soft reset on the job.

Specified by:
softReset in interface Resetable
Overrides:
softReset in class StructuralJob<Object>
Returns:
true if successful.

hardReset

public boolean hardReset()
Perform a hard reset. The super method is overridden so as not to reset the child but destroy them.

Specified by:
hardReset in interface Resetable
Overrides:
hardReset in class StructuralJob<Object>
Returns:
true if successful.

getPersister

public OddjobPersister getPersister()
Returns:
Returns the persister.

setPersister

public void setPersister(OddjobPersister persister)
Parameters:
persister - The persister to set.

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.

getLastReset

public org.oddjob.Oddjob.Reset getLastReset()
Getter for last reset.

Returns:

getArgs

public String[] getArgs()
Returns:
Returns the args.

setArgs

public void setArgs(String[] args)
Parameters:
args - The args to set.

getExport

public ArooaValue getExport(String key)
Getter

Parameters:
key - The key.
Returns:
A value.

setExport

public void setExport(String key,
                      ArooaValue value)
Setter.

Parameters:
key -
value -

getProperties

public Properties getProperties()
Getter.

Returns:
Properties, if set, or null.

setProperties

public void setProperties(Properties properties)
Setter.

Parameters:
properties - Optional properties.

getInheritance

public OddjobInheritance getInheritance()
Getter.

Returns:
Inheritance property.

setInheritance

public void setInheritance(OddjobInheritance inheritance)
Setter.

Parameters:
inheritance - Inheritance property.

getDir

public File getDir()

Property: dir

Description: The name of the directory the configuration file is in.

Required: R/O

Returns:
The directory path.

getVersion

public String getVersion()

Property: version

Description: This Oddjob's version.

Returns:
The version.

getDescriptorFactory

public ArooaDescriptorFactory getDescriptorFactory()
Getter.

Returns:
An ArooaDescriptorFactory or null.

setDescriptorFactory

public void setDescriptorFactory(ArooaDescriptorFactory descriptorFactory)
Setter.

Parameters:
descriptorFactory - And ArooaDescriptorFactory.

getOddjobExecutors

public OddjobExecutors getOddjobExecutors()
Getter for OddjobExecutors that have been given to this instance of Oddjob. This getter does not expose the internal executors.

Returns:
OddjobExecutors or null.

setOddjobExecutors

public void setOddjobExecutors(OddjobExecutors executors)
Setter.

Parameters:
executors - OddjobExecutors

getOddjobServices

public OddjobServices getOddjobServices()
Getter for OddjobServices.

Returns:

setOddjobServices

@Inject
public void setOddjobServices(OddjobServices oddjobServices)
Allow for injection of OddjobServices

Parameters:
oddjobServices -

toString

public String toString()
Description copied from class: BasePrimary
Override toString.

Overrides:
toString in class BasePrimary

getInputHandler

public InputHandler getInputHandler()
Getter.

Returns:
An InputHandler.

setInputHandler

public void setInputHandler(InputHandler inputHandler)
Setter.

Parameters:
inputHandler - An InputHandler.