org.oddjob.jobs.structural
Class SequentialJob

java.lang.Object
  extended by org.oddjob.framework.BaseComponent
      extended by org.oddjob.framework.BasePrimary
          extended by org.oddjob.framework.StructuralJob<Object>
              extended by 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, stateHandler, stop, structuralState
 
Fields inherited from class org.oddjob.framework.BaseComponent
iconHelper
 
Constructor Summary
SequentialJob()
           
 
Method Summary
 void execute()
          Execute this job.
 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, isStop, onDestroy, onReset, 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 ACTIVE.

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

getStateOperator

public StateOperator getStateOperator()

getInitialStateOp

public 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)