Package org.oddjob.jobs.structural

Class SequentialJob

java.lang.Object
org.oddjob.framework.extend.BaseComponent
org.oddjob.framework.extend.BasePrimary
org.oddjob.framework.extend.StructuralJob<Object>
org.oddjob.jobs.structural.SequentialJob
All Implemented Interfaces:
Serializable, Runnable, ArooaContextAware, ArooaSessionAware, Forceable, OptionallyTransient, PropertyChangeNotifier, Iconic, LogEnabled, Resettable, Stateful, Stoppable, Structural
public class SequentialJob extends StructuralJob<Object> implements Structural, Stoppable, OptionallyTransient
Author:
Rob Gordon
See Also:

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>
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.

  • Constructor Details

    • SequentialJob

      public SequentialJob()

  • Method Details

    • setStateOperator

      public void setStateOperator(StateOperator stateOperator)
      Parameters:
      stateOperator - The state operator to be applied to children's states to derive our state.
      Reference 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.

    • 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.
      Parameters:
      child - A child
      Reference Property:
      jobs

      Description

      The child jobs.
      Required:
      No, but pointless if missing.

    • 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.

    • waitForChildrenOnStop

      protected boolean waitForChildrenOnStop()
      Overrides:
      waitForChildrenOnStop in class StructuralJob<Object>

    • isIndependent

      public boolean isIndependent()

    • setIndependent

      public void setIndependent(boolean independent)
      Set whether children are considered dependent (false, default) or independent (true).
      Parameters:
      independent - flag value to set
      Reference Property:
      independent

      Description

      Whether the child jobs are independent or not.
      Required:
      Default is dependent child jobs.

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