State and Flow

Changing direction.

• Overview
• If and Trigger
• Wait and Join
• State Conditions
• Events

Overview

Deciding whether something needs to be done or not is often a job in itself, and Oddjob takes this view too. Rather than have a job that runs if a property is set or a file available, Oddjob has jobs that checks if a property is set (check) or a file is available (exists) and jobs that execute depending on the state of the jobs that did the checking.

If and Trigger

There are two main jobs that can be used to do something depending on the outcome of a job. They are:

if

Checks the state of it's first child job to decide what to do.

trigger

Execute the child job when a job elsewhere enters a specific state.

Trigger was introduced in the scheduling section of this manual, because it was developed sharing a lot of functionality with timer and retry and so was placed in the scheduling namespace. Conceptionally though it is more related to the state jobs and so is included here too.

The big difference between them is that the if job is synchronous and state is evaluated after the child job runs, where as the trigger job is asynchronous. Oddjob activates the trigger then moves on to execute the next job. The trigger will then fire (or cancel itself) at some point in the future depending on the state of the job it depends on.

Wait and Join

There are also two jobs that will stop Oddjob from executing anything else until another job is in a certain state. They are:

join

Executes it's child and waits for the child to finish executing before continuing.

wait

Waits for a job elsewhere to be in a specific state before allowing Oddjob to continue. Wait will also wait for a period of time or for a job to have a property before continuing.

Both these jobs block Oddjob, which is OK in small configurations but could leave too many threads blocked and thus hog resources in larger deployments. It's nearly always possible to come up with an alternative configuration using other jobs listed on this page.

State Conditions

The join job will only continue it's child job has finished running. The if, trigger and wait jobs take a property that is a State Condition that tests states to see if the condition is met. This provides more flexibility than just checking a job is in a single state. Oddjob provides a number of useful State Conditions with a conversion from a text constant (you can set the property with a single word).

The provided State Conditions are:

READY

Is a job ready?

RUNNING

Is a job executing or otherwise active?

INCOMPLETE

Is a job incomplete?

COMPLETE

Is a job complete?

EXCEPTION

Is a job in an exception state?

DESTROYED

The job has been destroyed. It can no longer be used. Note that many Jobs that use state conditions will enter an EXCEPTION state if the job they trigger on is destroyed, and so this state condition will not be met.

FAILURE

The state is either INCOMPLETE or EXCEPTION.

FINISHED

The state is either COMPLETE, INCOMPLETE or EXCEPTION.

EXECUTING

A job state is either EXECUTING or the state of a service is STARTING.

STARTED

A service has STARTED.

An '!' can also be place in front of any of these state conditions to negate them.

As stated previously, the join has it's state condition hard coded. That value is equivalent to !RUNNING. Note that this is different to FINISHED because finished does not include the READY state.

Events

Oddjob 1.6 introduces events. The idea is to allow jobs to trigger from events other than state changes.

The starting points are:

events:when

When an event occurs run a job. This happens continuously.

events:trigger

Run a job once when an event occurs. Subsequent events are ignored.

Currently supported event types are:

state:watch

Watch job state changes.

events:file

Watch file events,

Event logic can be combined with:

events:list

Combine a static list of event sources.

events:for

Combine a dynamic list of event sources