Raw configuration.
Oddjob Designer provides a user interface onto an Oddjob configuration file but it has it's limitations. At the moment it doesn't even validate the configuration. At some point you will have to understand the raw configuration files and in this guide that point is now.
Oddjob configuration files are written in XML. If you don't know XML then Google for a tutorial - it will take about an hour to pick up the basics.
Each Oddjob file contains an Oddjob and may contain 0 or 1 jobs for Oddjob to run.
A file with no job for oddjob to run is a complete waste of time but perfectly legal. The document element must always be <oddjob>.
<oddjob/>
A file with one job would be something like:
<oddjob> <echo text="Hello World!"/> </oddjob>
Here Oddjob treats any child element as a job. The element name is used to create the type of job it is.
Note that the attribute text is used to set the 'text' property of the echo job.
As mentioned before, Oddjob will only run a single job, so to run more than one job that single job must be capable of running several other jobs. A typical configuration using the sequential job would be as follows:
<oddjob>
<sequential>
<echo text="This is followed..."/>
<echo text="...By this"/>
</sequential>
</oddjob>
Here all elements of the sequential job declare the child jobs that the sequential job can run.
By using sequential and parallel jobs within each other complicated dependencies can be built up.
Elements are not always used to declare child jobs - they are also used to define more complicated properties of the job - those that can not be defined with a simple text attribute alone.
In this example we see the <repeat> job being configured with both elements that declare a child job and a schedule property.
<oddjob>
<repeat>
<schedule>
<interval interval="00:00:10"/>
</schedule>
<child>
<echo text="Hello"/>
</child>
</sequential>
</oddjob>
To define a property set at runtime from another job's property, simply use the ${id.property} construct in an attribute with a name matching the property.
This file will have exactly the same effect as the previous example.
<oddjob>
<sequential>
<variables id="shared-schedules">
<schedule name="regular">
<interval interval="00:00:10"/>
</schedule>
</variables>
<repeat schedule="${shared-schedules.regular}">
<child>
<echo text="Hello"/>
</child>
</sequential>
</oddjob>
Note that <schedule> element in the repeat job has been replaced by a schedule attribute. Properties are either attributes with a name matching the job's property or elements of the same name. Which is required depends on the complexity of the property being set.
The fact that the schedule element of the variables definition has the same name as the property of the repeat job is pure coincidence. In the variables job the schedule element declares a property 'regular' of type schedule not a property called schedule as it did in the repeat job. How an element name is interpreted can be slightly confusing to begin with but allows complicated configurations to be declared in XML that is as simple as possible.
In addition to accessing the simple properties of a job using the notation ${job-id.property} Oddjob also supports setting and getting indexed properties mapped properties and nested properties.
An indexed property is when a job provides a property which is a list that contains a number of items and supports accessing those items individually using it position in the list which is the items index. Not many jobs support indexed access to properties because it is seldom required. The notable exception is the Oddjob job which itself which has the 'args' property which is a list of arguments that can be used in the configuration file.
The notation for an indexed property is ${job-id.property[index]}.
A mapped property is when a job provides a property which is a map of keys to values and a particular value can be extracted using the key. Where they are available their exact use is documented in the reference.
The notation for an indexed property is ${job-id.property(key)}.
A nested property is where the job provides a property that itself has properties. These are rare but the format should be noted.
The notation for a mapped property is ${job-id.property.sub-property}.
The jobs and properties of a nested Oddjob are available using the path like notation ${nested-oddjob-id/job-id.property}
Here is an Oddjob configuration that contains an Oddjob job. The nested Oddjob runs the configuration nested.xml
.
<oddjob>
<sequential>
<oddjob id="fred" file="nested.xml" name="Fred"/>
<echo text="${fred/message.text}"/>
</sequential>
</oddjob>
If nested.xml contains
<oddjob id="jane">
<sequential>
<echo id="message" text="This will be displayed twice!"/>
</sequential>
</oddjob>
Running the outer Oddjob would result in the message being displayed twice.
One interesting point is that the nested Oddjob has two sides. On the outside it is is fred and on the inside it is jane. On the outside ${fred/jane.name} is exactly the same as ${fred.name} which is Fred. On the inside it is only accessible as jane, it has no knowledge of being fred, although ${jane.name} is still 'Fred'
There is theoretically no limit to the number of nested Oddjobs and the property access notation just expands in the style ${a/b/c.property} as might be expected.