[Index]

oddjob


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.


Property Summary

args An array of arguments the Oddjob configuration can use.
classLoader The classLoader to use when loading the configuration.
configuration The configuration.
descriptorFactory An org.oddjob.arooa.deploy.ArooaDescriptorFactory that will be used when loading the configuration.
dir The name of the directory the configuration file is in.
export Values to be exported into the nested configuration.
file The name of the configuration file.
inheritance Set how an Oddjob should share the values and properties of it's parent.
inputHandler A handler for user input.
lastReset Used internally to remember which reset to apply after loading a configuration.
loadable Can Oddjob be loaded.
name A name, can be any text.
oddjobExecutors Executors for Oddjob to use.
oddjobServices Services for Oddjob to use.
persister A component which is able to save and restore jobs.
properties Properties to be set in the nested configuration.
stop Read only view of the internal stop flag.
version This Oddjob's version.

Example Summary

Example 1 Hello World with Oddjob.
Example 2 Using an argument passed into Oddjob that may or may not be set.
Example 3 Nesting Oddjob.
Example 4 A nested Oddjob with one argument passed to the child.
Example 5 A nested Oddjob with a property past to the child.
Example 6 Using export to pass values to a nested Oddjob.
Example 7 Examples elsewhere.

Property Detail

args

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

An array of arguments the Oddjob configuration can use.

classLoader

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

The classLoader to use when loading the configuration. This classloader will also be made available to child components that inject a classloader. This might not always be what is required as this classloader defaults to the application classloader not the Oddball classloader that will have loaded an Oddball component. This might be changed in future versions of Oddjob.

See also url-class-loader

configuration

Configured ByELEMENT
AccessWRITE_ONLY
RequiredEither this or file is required.

The configuration. An alternative to setting a file. This can be useful when the configuration is to come from some other input.

See also arooa:configuration

descriptorFactory

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

An org.oddjob.arooa.deploy.ArooaDescriptorFactory that will be used when loading the configuration. This augments Oddjob's internal descriptor, and allows custom jobs to have their own definitions.

See also arooa:descriptor, arooa:descriptors and oddballs

dir

AccessREAD_ONLY
RequiredR/O

The name of the directory the configuration file is in.

export

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo

Values to be exported into the nested configuration. Values will be registered in the inner oddjob using the key of this mapped property.

file

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo.

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

inheritance

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo. Defaults to PROPERTIES.

Set how an Oddjob should share the values and properties of it's parent. Valid values are:

NONE
No values or properties are automatically inherited.
PROPERTIES
All properties are inherited. Only properties are inherited, values must be exported explicitly using the export property.
SHARED
All properties and values are shared between the parent and child Oddjobs. Any properties or values set in the child will be visible in the parent. This setting is particularly useful for shared common configuration.

inputHandler

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

A handler for user input. This will be provided internally and will only be required in specialised situations.

lastReset

AccessREAD_ONLY

Used internally to remember which reset to apply after loading a configuration.

loadable

AccessREAD_ONLY
RequiredRead only.

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

name

Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo.

A name, can be any text.

oddjobExecutors

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

Executors for Oddjob to use. This is set automatically in Oddjob. For advanced use, user supplied org.oddjob.OddjobExecutors may be provided.

oddjobServices

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

Services for Oddjob to use. This is set automatically in Oddjob. Unlikely to be required.

persister

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo.

A component which is able to save and restore jobs.

See also file-persister and sql-persister-service.

properties

Configured ByELEMENT
AccessREAD_WRITE
RequiredNo

Properties to be set in the nested configuration. Can be set using a properties.

stop

AccessREAD_ONLY

Read only view of the internal stop flag. This flag is cleared with a reset.

version

AccessREAD_ONLY

This Oddjob's version.


Examples

Example 1

Hello World with Oddjob. Oddjob is configured to run the echo job.

<oddjob>
    <job>
        <echo id="echo">Hello World</echo>
    </job>
</oddjob>

Example 2

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 3

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 4

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 5

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 6

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 value. 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 7

Examples elsewhere.


(c) R Gordon Ltd 2005 - Present