XML configuration.
Oddjob Designer provides a user interface onto an Oddjob configuration file but it has its 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>
<job>
<echo>Hello World!</echo>
</job>
</oddjob>
Here we are defining a property called 'job'. The element name 'echo' 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.
Changing the root job to be sequential allows us to add more jobs.
<oddjob>
<job>
<sequential>
<jobs>
<echo>This is followed...</echo>
<echo>...By this</echo>
</jobs>
</sequential>
</job>
</oddjob>
We are already seeing that sometimes attributes are used to define properties of a job (like the text property of the echo job), and sometimes elements are (like job and jobs). By default text and numbers are set using attributes and more complicated properties are set using elements. This can be changed on a job by job basis but should be documented in the reference guide when it is.
Here is a more complicated example - we see the <scheduling:timer> job (which we'll learn more about later) being configured with both elements that declare a job property and a schedule property. Note that schedules are in a different XML namespace.
<oddjob xmlns:scheduling="http://rgordon.co.uk/oddjob/scheduling" xmlns:schedules="http://rgordon.co.uk/oddjob/schedules">
<job>
<scheduling:timer>
<schedule>
<schedules:interval interval="00:00:10"/>
</schedule>
<job>
<echo>Hello</echo>
</job>
</scheduling:timer>
</job>
</oddjob>
All this XML is probably looking a bit ungainly but there is a pattern to it that makes understanding it a bit easier. Here's the pattern in the previous example:
<oddjob>
<property>
<type>
<property>
<type/>
</property>
<property>
<type/>
</property>
</type>
</property>
</oddjob>
Do you See it? Elements Are either property elements, which are the name of the property being set, or type elements which are the type of property - be it a job property (copy, delete) or other value property (file, schedule).
We saw in the last section that properties can be set from other job's properties when the job runs. However we only saw how this worked in attribute properties using the ${id.property} construct. When the property is defined by an element use the 'value' element type to define a reference.
This file will have exactly the same effect as the previous example.
<oddjob xmlns:scheduling="http://rgordon.co.uk/oddjob/scheduling" xmlns:schedules="http://rgordon.co.uk/oddjob/schedules">
<job>
<sequential>
<jobs>
<variables id="shared-schedules">
<regular>
<schedules:interval interval="00:00:10"/>
</regular>
</variables>
<scheduling:timer>
<schedule>
<value value="${shared-schedules.regular}"/>
</schedule>
<job>
<echo>Hello</echo>
</job>
</scheduling:timer>
</jobs>
</sequential>
</job>
</oddjob>
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 id="this">
<job>
<sequential>
<jobs>
<oddjob id="fred" name="Fred" file="${this.dir}/nested.xml"/>
<echo>${fred/message.text}</echo>
</jobs>
</sequential>
</job>
</oddjob>
If nested.xml contains
<oddjob id="jane">
<job>
<echo id="message">This will be displayed twice!</echo>
</job>
</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.
The nested oddjob configuration was defined using '${this.dir}/nested.xml' - Oddjob exposes the directory of it's configuration file using a read-only property called 'dir', and the parent Oddjob has been given the id 'this' so our configuration file expression expands to 'The file nested.xml in the same directory as the configuration file of our parent Oddjob'.