Package org.oddjob

Class Oddjob

java.lang.Object
org.oddjob.framework.extend.BaseComponent
org.oddjob.framework.extend.BasePrimary
org.oddjob.framework.extend.StructuralJob<Object>
org.oddjob.Oddjob
All Implemented Interfaces:
Serializable, Runnable, ArooaContextAware, ArooaSessionAware, ConfigurationOwner, BeanDirectoryOwner, Describer, Forceable, PropertyChangeNotifier, Iconic, Loadable, LogEnabled, Resettable, Stateful, Stoppable, Structural
public class Oddjob extends StructuralJob<Object> implements Loadable, ConfigurationOwner, BeanDirectoryOwner, Describer
Read a configuration, creates child jobs and executes them.
Author:
Rob Gordon
See Also:

Description

The starting point for a hierarchy of jobs. The Oddjob job creates and runs a job hierarchy by processing a supplied configuration.

Oddjob creates a 'root' job on which to create the hierarchy. Through this root Oddjob aquires the first job to run and also exposes some of it's own properties for the jobs in the configuration to use. The root job's properties are:

job
The top level job. This is the single job that Oddjob runs. This property is optional but Oddjob won't do much if a job for it to run isn't supplied. This is the Oddjob root's only writeable property and is write only.
file
The path of the configuration file that Oddjob has loaded. Read Only.
dir
The path of the configuration file's directory. Read Only.
args
An array of arguments passed in on the command line or from a parent Oddjob. See below. Read Only.
services
Provides access to Oddjobs underlying services. Used by the frameworks automatic configuration mechanism to configure the properties of jobs that are documented as set automatically. May be ignored for every day use. Read Only.

For these properties to be accessible the root oddjob must be given an id. As can be seen from the examples, the author uses the id 'this' but the choice is arbitrary.

Nesting Oddjobs

An Oddjob job allows an Oddjob instance to be created within an existing Oddjob configuration. This way complicated processes can be created in manageable and separately testable units.

Properties of jobs in a nested Oddjob can be accessed using the notation ${nested-oddjob-id/job-id.property} where nested-oddjob-id is the id in the outer configuration, not the inner one. Saving Oddjob's State

The persister property on a nested Oddjob will allow it's state to be saved. See the User Guide for more information on how to set a persister. Customising Oddjob

Oddjob's descriptorFactory and classLoader properties allow bespoke components and types to be used. The developer guide is all about writing custom job's for Oddjob.

Example

Hello World with Oddjob. Oddjob is configured to run the EchoJob job. 
<oddjob>

    <job>

        <echo id="echo">Hello World</echo>

    </job>

</oddjob>
Using an argument passed into Oddjob that may or may not be set. 
<oddjob id="this">

    <job>

        <sequential>

            <jobs>

                <state:if xmlns:state="http://rgordon.co.uk/oddjob/state">

                    <jobs>

                        <check value="${this.args[0]}"/>

                        <properties>

                            <values>

                                <value key="our.file.name" value="${this.args[0]}"/>

                            </values>

                        </properties>

                        <input>

                            <requests>

                                <input-text prompt="File Name?" property="our.file.name"/>

                            </requests>

                        </input>

                    </jobs>

                </state:if>

                <echo>File Name is ${our.file.name}</echo>

            </jobs>

        </sequential>

    </job>

</oddjob>
Nesting Oddjob. Note how the dir property of the Oddjob root is used as the path of the nested configuration file. 
<oddjob id="this">

    <job>

        <sequential>

            <jobs>

                <oddjob id="nested" file="${this.dir}/HelloWorld.xml"/>

                <echo>Nested job said: ${nested/echo.text}</echo>

            </jobs>

        </sequential>

    </job>

</oddjob>

The nested job is the first example: 

<oddjob>

    <job>

        <echo id="echo">Hello World</echo>

    </job>

</oddjob>
This example also shows how a property within the nested file can be accessed within the parent configuration.A nested Oddjob with one argument passed to the child. 
<oddjob id="this">

    <job>

        <oddjob id="nested" file="${this.dir}/EchoArg.xml">

            <args>

                <list>

                    <values>

                        <value value="Hello World"/>

                    </values>

                </list>

            </args>

        </oddjob>

    </job>

</oddjob>
And EchoArg.xml: 
<oddjob id="this">

    <job>

        <echo id="echo">${this.args[0]}</echo>

    </job>

</oddjob>
A nested Oddjob with a property past to the child. 
<oddjob id="this">

    <job>

        <oddjob id="nested" file="${this.dir}/EchoProperty.xml">

            <properties>

                <properties>

                    <values>

                        <value key="our.greeting" value="Hello World"/>

                    </values>

                </properties>

            </properties>

        </oddjob>

    </job>

</oddjob>
And EchoProperty.xml: 
<oddjob id="this">

    <job>

        <echo id="echo">${our.greeting}</echo>

    </job>

</oddjob>
Unlike the properties of jobs, free format properties like this can't be accessed using the nested convention. 
 ${nested/our.greeting} DOES NOT WORK!
This may be fixed in future versions.Using export to pass values to a nested Oddjob. 
<oddjob>

    <job>

        <sequential>

            <jobs>

                <folder>

                    <jobs>

                        <echo id="secret">I'm a secret job</echo>

                    </jobs>

                </folder>

                <oddjob id="inner">

                    <export>

                        <value key="secret" value="${secret}"/>

                    </export>

                    <configuration>

                        <arooa:configuration xmlns:arooa="http://rgordon.co.uk/oddjob/arooa">

                            <xml>

                                <xml>

                                    <oddjob>

                                        <job>

                                            <run job="${secret}"/>

                                        </job>

                                    </oddjob>

                                </xml>

                            </xml>

                        </arooa:configuration>

                    </configuration>

                </oddjob>

            </jobs>

        </sequential>

    </job>

</oddjob>
Here a job is exported into a nested Oddjob. The exported object is actually a ValueType. The value is converted back to the job when the job property of the run job is set. Expressions such as ${secret.text} are not valid (because value does not have a text property!). Even ${secret.value.text} will not work because of value wraps the job in yet another layer of complexity.Examples elsewhere.

  • Field Details

    • ODDJOB_ELEMENT

      public static final ArooaElement ODDJOB_ELEMENT
      The document root for an Oddjob configuration file.

  • Constructor Details

    • Oddjob

      public Oddjob()
      Only constructor.

  • Method Details

    • setFile

      public void setFile(File file)
      Parameters:
      file - The file name.
      Reference Property:
      file

      Description

      The name of the configuration file. to configure this oddjob.
      Required:
      No.

    • getFile

      public File getFile()

    • setConfiguration

      public void setConfiguration(ArooaConfiguration config)
      Setter for configuration.
      Parameters:
      config -

    • setClassLoader

      public void setClassLoader(ClassLoader classLoader)
      Reference Property:
      classLoader

      Description

      The classLoader to use when loading the configuration. This classloader will also be made available to child components that inject a classloader. This might not always be what is required as this classloader defaults to the application classloader not the Oddball classloader that will have loaded an Oddball component. This might be changed in future versions of Oddjob.

      See also URLClassLoaderType

      Required:
      No.

    • getClassLoader

      public ClassLoader getClassLoader()
      Return a class loader. If one has not been set return the class loader which loaded this class.
      Returns:
      A classLoader.

    • provideConfigurationSession

      public ConfigurationSession provideConfigurationSession()
      Description copied from interface: ConfigurationOwner
      Provide a ConfigurationSession.
      Specified by:
      provideConfigurationSession in interface ConfigurationOwner
      Returns:
      A ConfigurationSession. May be null if no session is available.

    • addOwnerStateListener

      public void addOwnerStateListener(OwnerStateListener listener)
      Description copied from interface: ConfigurationOwner
      Add a listener.
      Specified by:
      addOwnerStateListener in interface ConfigurationOwner
      Parameters:
      listener -

    • removeOwnerStateListener

      public void removeOwnerStateListener(OwnerStateListener listener)
      Description copied from interface: ConfigurationOwner
      Remove a listener.
      Specified by:
      removeOwnerStateListener in interface ConfigurationOwner
      Parameters:
      listener -

    • rootDesignFactory

      public SerializableDesignFactory rootDesignFactory()
      Description copied from interface: ConfigurationOwner
      Get the design factory for the configuration. If this is null the Oddjob Explorer won't show a DesignInside action.

      Note that this is a SerializableDesignFactory so that this interface can be represented remotely.

      Specified by:
      rootDesignFactory in interface ConfigurationOwner
      Returns:
      A DesignFactory. Must not be null if a ConfigurationSession is available.

    • rootElement

      public ArooaElement rootElement()
      Description copied from interface: ConfigurationOwner
      Get the root element.
      Specified by:
      rootElement in interface ConfigurationOwner
      Returns:
      The root element of the configuration. Must not be null if a ConfigurationSession is available.

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

    • isLoadable

      public boolean isLoadable()
      Description copied from interface: Loadable
      Is the component currently loadable.
      Specified by:
      isLoadable in interface Loadable
      Returns:
      true if the component can be loaded, false otherwise.
      Reference Property:
      loadable

      Description

      Can Oddjob be loaded. Used by the Load/Unload actions.
      Required:
      Read only.

    • load

      public void load()
      Description copied from interface: Loadable
      Load the component.
      Specified by:
      load in interface Loadable

    • execute

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

    • unload

      public void unload()
      Description copied from interface: Loadable
      Unload the component.
      Specified by:
      unload in interface Loadable

    • onDestroy

      protected void onDestroy()
      Description copied from class: BaseComponent
      Subclasses override this method to clear up resources. This is called by the framework before child elements have been destroyed.
      Overrides:
      onDestroy in class StructuralJob<Object>

    • softReset

      public boolean softReset()
      Description copied from class: StructuralJob
      Perform a soft reset on the job.
      Specified by:
      softReset in interface Resettable
      Overrides:
      softReset in class StructuralJob<Object>
      Returns:
      true if successful.

    • hardReset

      public boolean hardReset()
      Perform a hard reset. The super method is overridden so as not to reset the child but destroy them.
      Specified by:
      hardReset in interface Resettable
      Overrides:
      hardReset in class StructuralJob<Object>
      Returns:
      true if successful.

    • getPersister

      public OddjobPersister getPersister()
      Returns:
      Returns the persister.

    • setPersister

      public void setPersister(OddjobPersister persister)
      Parameters:
      persister - The persister to set.

    • provideBeanDirectory

      public BeanDirectory provideBeanDirectory()
      Description copied from interface: BeanDirectoryOwner
      Get the BeanDirectory. This method may return null if the BeanDirectory isn't available.
      Specified by:
      provideBeanDirectory in interface BeanDirectoryOwner
      Returns:
      The BeanDirectory or null.

    • describe

      public Map<String,String> describe(Object bean)
      Description copied from interface: Describer
      Describe a bean.
      Specified by:
      describe in interface Describer
      Parameters:
      bean - The bean.
      Returns:
      Return a map which is a description of the properties.

    • getLastReset

      public org.oddjob.Oddjob.Reset getLastReset()
      Getter for last reset.
      Returns:

    • getArgs

      public String[] getArgs()
      Returns:
      Returns the args.

    • setArgs

      public void setArgs(String[] args)
      Parameters:
      args - The args to set.

    • getExport

      public ArooaValue getExport(String key)
      Getter
      Parameters:
      key - The key.
      Returns:
      A value.

    • setExport

      public void setExport(String key, ArooaValue value)
      Setter.
      Parameters:
      key -
      value -

    • getProperties

      public Properties getProperties()
      Getter.
      Returns:
      Properties, if set, or null.

    • setProperties

      public void setProperties(Properties properties)
      Setter.
      Parameters:
      properties - Optional properties.

    • getInheritance

      public OddjobInheritance getInheritance()
      Getter.
      Returns:
      Inheritance property.

    • setInheritance

      public void setInheritance(OddjobInheritance inheritance)
      Setter.
      Parameters:
      inheritance - Inheritance property.

    • getDir

      public File getDir()
      Returns:
      The directory path.
      Reference Property:
      dir

      Description

      The name of the directory the configuration file is in.
      Required:
      R/O

    • getVersion

      public String getVersion()
      Returns:
      The version.
      Reference Property:
      version

      Description

      This Oddjob's version.

    • getDescriptorFactory

      public ArooaDescriptorFactory getDescriptorFactory()
      Getter.
      Returns:
      An ArooaDescriptorFactory or null.

    • setDescriptorFactory

      public void setDescriptorFactory(ArooaDescriptorFactory descriptorFactory)
      Setter.
      Parameters:
      descriptorFactory - And ArooaDescriptorFactory.

    • getOddjobExecutors

      public OddjobExecutors getOddjobExecutors()
      Getter for OddjobExecutors that have been given to this instance of Oddjob. This getter does not expose the internal executors.
      Returns:
      OddjobExecutors or null.

    • setOddjobExecutors

      public void setOddjobExecutors(OddjobExecutors executors)
      Setter.
      Parameters:
      executors - OddjobExecutors

    • getOddjobServices

      public OddjobServices getOddjobServices()
      Getter for OddjobServices.
      Returns:

    • setOddjobServices

      @Inject public void setOddjobServices(OddjobServices oddjobServices)
      Allow for injection of OddjobServices
      Parameters:
      oddjobServices -

    • toString

      public String toString()
      Description copied from class: BasePrimary
      Override toString.
      Overrides:
      toString in class BasePrimary

    • getInputHandler

      public InputHandler getInputHandler()
      Getter.
      Returns:
      An InputHandler.

    • setInputHandler

      public void setInputHandler(InputHandler inputHandler)
      Setter.
      Parameters:
      inputHandler - An InputHandler.