Oddjob (Oddjob 1.5.0 API)

java.lang.Object
- org.oddjob.framework.BaseComponent
- - org.oddjob.framework.BasePrimary
  - - org.oddjob.framework.StructuralJob<Object>
    - - 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.
- FilePersister
- SQLPersisterService
- OddballsDescriptorFactory
- URLClassLoaderType
See Also:
Serialized Form
Author:

Rob Gordon

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`Oddjob.OddjobRoot` The object which is the Oddjob root.
`static class`	`Oddjob.OddjobRootArooa` Provide an `ArooaBeanDescriptor` for the root Oddjob bean.

Field Summary

Fields
Modifier and Type Field and Description

static ArooaElement ODDJOB_ELEMENT
The document root for an Oddjob configuration file.
- Fields inherited from class org.oddjob.framework.StructuralJob
  childHelper, childStateReflector, destroy, stop, structuralState

Fields
Modifier and Type	Field and Description
`static ArooaElement`	`ODDJOB_ELEMENT` The document root for an Oddjob configuration file.

Constructor Summary

Constructors
Constructor and Description

Oddjob()
Only constructor.

Constructors
Constructor and Description
`Oddjob()` Only constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`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.
`SerializableDesignFactory`	`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, iconHelper, isStop, onHardReset, onReset, onSoftReset, 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
  - 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 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 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. This is called by the framework before child elements have been destroyed.
    
    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.

Class Oddjob

Description

Nesting Oddjobs

Saving Oddjob's State

Customising Oddjob

Example

Example

Example

Example

Example

Example

Example

Nested Class Summary

Field Summary

Fields inherited from class org.oddjob.framework.StructuralJob

Constructor Summary

Method Summary

Methods inherited from class org.oddjob.framework.StructuralJob

Methods inherited from class org.oddjob.framework.BasePrimary

Methods inherited from class org.oddjob.framework.BaseComponent

Methods inherited from class java.lang.Object

Methods inherited from interface org.oddjob.Stateful

Field Detail

ODDJOB_ELEMENT

Constructor Detail

Oddjob

Method Detail

setFile

getFile

setConfiguration

setClassLoader

getClassLoader

provideConfigurationSession

addOwnerStateListener

removeOwnerStateListener

rootDesignFactory

rootElement

getInitialStateOp

isLoadable

load

execute

unload

onDestroy

softReset

hardReset

getPersister

setPersister

provideBeanDirectory

getLastReset

getArgs

setArgs

getExport

setExport

getProperties

setProperties

getInheritance

setInheritance

getDir

getVersion

getDescriptorFactory

setDescriptorFactory

getOddjobExecutors

setOddjobExecutors

getOddjobServices

setOddjobServices

toString

getInputHandler

setInputHandler