org.oddjob.jobs.structural

Class SequentialJob

java.lang.Object

org.oddjob.framework.BaseComponent

org.oddjob.framework.BasePrimary

org.oddjob.framework.StructuralJob<Object>

org.oddjob.jobs.structural.SequentialJob

All Implemented Interfaces:

Serializable, Runnable, ArooaContextAware, ArooaSessionAware, Forceable, OptionallyTransient, PropertyChangeNotifier, Iconic, LogEnabled, Resetable, Stateful, Stoppable, Structural

public class SequentialJob
extends StructuralJob<Object>
implements Structural, Stoppable, OptionallyTransient

Description

Executes it's children in a sequence one after the other. The sequence will only continue to be executed if each child COMPLETEs. If a child is INCOMPLETE, or throws an EXCEPTION then execution will terminate and this job's state will reflect that of the failed child.

This behaviour can be changed by setting the independent property which will cause execution to continue regardless of the last executed child state.

State Operator

The stateOperator property changes the way in which this jobs state reflects its child states. Oddjob currently supports the following State Operators:

ACTIVE

If any child is EXECUTING, ACTIVE or STARTING this job's state will be ACTIVE. Otherwise, if a child is STARTED, this job's state will be STARTED. Otherwise, if a child is READY, this job's state will be READY. Otherwise, this job's state will reflect the worst state of the child jobs.

WORST

This job's state will be EXCEPTION or INCOMPLETE if any of the child job's are in this state. Otherwise the rules for ACTIVE apply.

SERVICES

This state operator is designed for starting services. This job will COMPLETE when all services are STARTED. If any services fails to start this job reflects the EXCEPTION state. Because this job, when using this state operator, completes even though it's children are running, this job is analogous to creating daemon threads in that the services will not stop Oddjob from shutting down once all other jobs have completed.

Stopping

As with other structural jobs, when this job is stopping, either because of a manual stop, or during Oddjob's shutdown cycle, the child jobs and services will still be stopped in an reverse order.

Persistence

If this job has an Id and Oddjob is running with a Persister, then this job's state will be persisted when it changes. Thus a COMPLETE state will be persisted once all child jobs have completed. If Oddjob is restarted at this point the COMPLETE state of this job will stop the child job's from re-running, if though they themselves might not have been persisted. To stop this job from being persisted set the transient property to true. Not that when starting services with this job, persistence is probably not desirable as it will stop the services from re-starting.

Re-running Child Jobs

If the failed job is later run manually and completes this Job will reflect the new state. As such it is useful as a trigger point for the completion of a sequence of jobs.

Example

A simple sequence of two jobs.

<oddjob>
    <job>
        <sequential name="A sequence of two jobs">
            <jobs>
                <echo>This runs first.</echo>
                <echo>This runs after.</echo>
            </jobs>
        </sequential>
    </job>
</oddjob>

Example

Starting two services. To perform odd jobs, in a workshop for instance, this first 'job' is to turn on the lights and turn on any machines required. The service manager encompasses this idea - and this example embelishes the idea. Real odd jobs for Oddjob will involve activities such as starting services such as a data source or a server connection. The concept however is still the same.

<oddjob>
  <job>
    <sequential>
      <jobs>
      <sequential id="service-manager" stateOperator="SERVICES">
        <jobs>
          <bean id="lights" class="org.oddjob.jobs.structural.ServiceManagerTest$Lights"/>
          <bean id="machine" class="org.oddjob.jobs.structural.ServiceManagerTest$MachineThatGoes" goes="ping"/>
        </jobs>
      </sequential>
      <echo>The lights are ${lights.are} and the machine goes ${machine.goes}.</echo>
      </jobs>
    </sequential>
  </job>
</oddjob>

The services are started in order. Once both services have started a job is performed that requires both services. If this configuration were running from the command line, Oddjob would stop the services as it shut down. First the machine would be turned of and then finally the lights would be turned out.

See Also:

Serialized Form

Author:

Rob Gordon

Field Summary

Fields inherited from class org.oddjob.framework.StructuralJob

childHelper, childStateReflector, destroy, stop, structuralState

Constructor Summary

Constructors

Constructor and Description
SequentialJob()

Method Summary

Methods

Modifier and Type	Method and Description
void	execute() Execute this job.
protected StateOperator	getInitialStateOp() Subclasses must provide the StateOperator that will decide how to evaluate the children's state.
StateOperator	getStateOperator()
boolean	isIndependent()
boolean	isTransient() Is the component transient.
void	setIndependent(boolean independent) Set whether children are considered dependent (false, default) or independent (true).
void	setJobs(int index, Object child) Add a child.
void	setStateOperator(StateOperator stateOperator)
void	setTransient(boolean _transient)

Methods inherited from class org.oddjob.framework.StructuralJob

addStructuralListener, fireDestroyedState, force, getStateChanger, hardReset, iconHelper, isStop, onDestroy, onHardReset, onReset, onSoftReset, onStop, removeStructuralListener, run, softReset, startChildStateReflector, stateHandler, stop

Methods inherited from class org.oddjob.framework.BasePrimary

configure, getName, logger, logger, loggerName, save, setName, toString

Methods inherited from class org.oddjob.framework.BaseComponent

addIconListener, addPropertyChangeListener, addStateListener, configure, destroy, firePropertyChange, getArooaSession, iconForId, initialise, lastStateEvent, onConfigured, onInitialised, removeIconListener, removePropertyChangeListener, removeStateListener, save, setArooaContext, setArooaSession

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.oddjob.Structural

addStructuralListener, removeStructuralListener

Methods inherited from interface org.oddjob.Stoppable

stop

Methods inherited from interface org.oddjob.Stateful

addStateListener, lastStateEvent, removeStateListener

Constructor Detail

SequentialJob

public SequentialJob()

Method Detail

setStateOperator

public void setStateOperator(StateOperator stateOperator)

Property: stateOperator

Description: Set the way the children's state is evaluated and reflected by the parent. Values can be WORST, ACTIVE, or SERVICES.

Required: No, default is WORST.

Parameters:

stateOperator - The state operator to be applied to children's states to derive our state.

getStateOperator

public StateOperator getStateOperator()

getInitialStateOp

protected StateOperator getInitialStateOp()

Description copied from class: StructuralJob

Subclasses must provide the StateOperator that will decide how to evaluate the children's state.

Specified by:

getInitialStateOp in class StructuralJob<Object>

Returns:

A State Operator. Must not be null.

setJobs

public void setJobs(int index,
           Object child)

Add a child.

Property: jobs

Description: The child jobs.

Required: No, but pointless if missing.

Parameters:

child - A child

execute

public void execute()
             throws Exception

Description copied from class: StructuralJob

Execute this job.

Specified by:

execute in class StructuralJob<Object>

Throws:

Exception - If the unexpected occurs.

isIndependent

public boolean isIndependent()

setIndependent

public void setIndependent(boolean independent)

Set whether children are considered dependent (false, default) or independent (true).

Property: independent

Description: Whether the child jobs are independent or not.

Required: Default is dependent child jobs.

Parameters:

independent - flag value to set

isTransient

public boolean isTransient()

Description copied from interface: OptionallyTransient

Is the component transient.

Specified by:

isTransient in interface OptionallyTransient

Returns:

true if transient, false otherwise.

setTransient

public void setTransient(boolean _transient)