org.oddjob
Class Oddjob

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

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.