oddjob

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

Example Summary

Property Detail

An array of arguments the Oddjob configuration can use.

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

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

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

The name of the directory the configuration file is in.

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

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

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 By	ELEMENT
Access	READ_WRITE
Required	No.

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

lastReset

Access

READ_ONLY

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

loadable

Access	READ_ONLY
Required	Read only.

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

name

Configured By	ATTRIBUTE
Access	READ_WRITE
Required	No.

A name, can be any text.

oddjobExecutors

Configured By	ELEMENT
Access	READ_WRITE
Required	No.

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

oddjobServices

Configured By	ELEMENT
Access	READ_WRITE
Required	No.

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

persister

Configured By	ELEMENT
Access	READ_WRITE
Required	No.

A component which is able to save and restore jobs.

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

properties

Configured By	ELEMENT
Access	READ_WRITE
Required	No

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

stop

Access

READ_ONLY

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

version

Access

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

• file-persister
• sql-persister-service
• oddballs
• url-class-loader

---

(c) R Gordon Ltd 2005 - Present