Task (Jobman API)

java.lang.Object
- net.sourceforge.jobman.Task

Direct Known Subclasses:

Leaf, Node
```
abstract class Task
extends java.lang.Object
```
A job is uniquely defined by its name and its parameters. A parameter of a the job is a parameter of the job or its parent job of type plop or pfrk. An object of this class is designed to run in the main thread. Task exits by updateStatus() or kill(); The life cycle of a Task is as follows. BORN: The object is constructed. READY: It has some part ready to be executed. This means, some action can be taken if we don't consider its dependencies. CLEARED: All dependencies are cleared. All jobs that this job depends on have been completed. LOCKED: It has acquired the lock this job requires to run. QUEUED: It has been queued for execution. For a Leaf job, this means the job has placed the command into execution queue. For a Node job, this means the full list of parameterized child jobs is being worked. RUNNING: It is running. For a exec job, the job command is being executed. For plop/pfrk jobs, enough information has been gathered to form the full execution plan. For loop/fork jobs, LOCKED, QUEUED status should be changed to RUNNING without any further action. SUCCEEDED: The job has finished completely. BREAK means the job has completed successfully. Furthermore, it tells that its sibling jobs (other child jobs of its parent) don't need to be executed. FAILED: The job failed execution. Status BORN, READY, CLEARED, and LOCKED are preparing states of a job. Status QUEUED and RUNNING are executing states of a job. Status SUCCEEDED, BREAK, and FAILED are terminal states of the job. At a terminal state, the Task object does not exist any more.

Field Summary

Fields
Modifier and Type	Field and Description
`private int`	`level`
`protected java.lang.String`	`name` The name of the job.
`(package private) static char`	`nameParSep` Hyphen is used to separate job name and parameter string.
`private static java.lang.String`	`normalEx` This is the pattern for a non-word character.
`protected java.lang.String`	`param` The parameters to the job.
`protected Node`	`parent` The parent job or this job.
`private static java.lang.String`	`repEx` Underscore is used to replace all non-word characters in job parameters.
`private Status`	`stat` The status of this job, which is used to communicate to the parent task.
`private java.lang.String`	`strRep` The String representation of this Task.

Constructor Summary

Constructors
Constructor and Description

Task(Node parent, java.lang.String name, java.lang.String param)
Construct a job and set its status to READY.

Constructors
Constructor and Description
`Task(Node parent, java.lang.String name, java.lang.String param)` Construct a job and set its status to READY.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected abstract Status`	`advance()` Check the current status assuming the last update had status RUNNING.
`protected java.lang.String`	`debugDump()` Dump the current state of the job.
`protected abstract java.lang.String`	`dumpMore()`
`(package private) static java.lang.String`	`extractTaskName(java.io.File path)`
`protected java.util.LinkedHashMap<java.lang.String,java.lang.String>`	`fetchAncestry()` Fetch the the ancestry info of the job.
`private void`	`formStrRep()`
`(package private) int`	`getLevel()`
`(package private) java.lang.String`	`getName()` Get the name of the job.
`(package private) java.lang.String`	`getParam()` Get the parameters of the job.
`(package private) Status`	`getStatus()`
`protected boolean`	`hasSucceededLast()` For a resumed run, test if this job has completed in the previous run.
`(package private) void`	`ignore()`
`(package private) void`	`kill()` Try to stop the job assuming it has not successfully finished.
`(package private) void`	`markFail()`
`protected abstract void`	`terminate()` Forcibly terminate this job.
`java.lang.String`	`toString()` Get the string representation of the job.
`(package private) Status`	`updateStatus()` Obtain the status of the task.
`private void`	`updateStatusImpl()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - normalEx
```
private static final java.lang.String normalEx
```
    This is the pattern for a non-word character.
    
    See Also:
    
    Constant Field Values
  - repEx
```
private static final java.lang.String repEx
```
    Underscore is used to replace all non-word characters in job parameters.
    
    See Also:
    
    Constant Field Values
  - nameParSep
```
static final char nameParSep
```
    Hyphen is used to separate job name and parameter string.
    
    See Also:
    
    Constant Field Values
  - stat
```
private Status stat
```
    The status of this job, which is used to communicate to the parent task. Only this super class can directly update the status.
  - name
```
protected java.lang.String name
```
    The name of the job.
  - strRep
```
private java.lang.String strRep
```
    The String representation of this Task. It is the result of toString().
  - param
```
protected java.lang.String param
```
    The parameters to the job. It is the string concatenating words (ASCII/numbers/underscore) by spaces " ". For example, "par1 par2 par3". This can be null.
  - parent
```
protected Node parent
```
    The parent job or this job. Each Task has a parent Node except the top most one. The parent Node is the only object holding the Task object, except the following situation. If a Task is a exec job, then it is also held by Schedule when it is in the queue state. However, once the exec job starts execution, Schedule will release the Task object. This means once its parent Node release the Task, it will be subject to the garbage collection.
  - level
```
private int level
```
- Constructor Detail
  - Task
```
Task(Node parent,
     java.lang.String name,
     java.lang.String param)
throws java.lang.Exception
```
    Construct a job and set its status to READY. Once a Task is constructed, it is not subject to dynamic change. This means, re-reading of opt_dynamic.txt does not affect the member data of the Task object.
    
    Throws:
    
    java.lang.Exception
- Method Detail
  - getName
```
java.lang.String getName()
```
    Get the name of the job.
    
    Returns:
    
    the name of the job.
    
    See Also:
    
    name
  - getParam
```
java.lang.String getParam()
```
    Get the parameters of the job.
    
    Returns:
    
    the string concatenating all job parameters.
    
    See Also:
    
    param
  - getLevel
```
int getLevel()
```
  - fetchAncestry
```
protected java.util.LinkedHashMap<java.lang.String,java.lang.String> fetchAncestry()
```
    Fetch the the ancestry info of the job. A job is uniquely identified by its name and ancestry parameters. The two arguments are Vectors of the same length. The result is a vector of parameters for the job (including its own parameter). Each component of the Vector is a String, as a parameter for its ancestor job. Each ancestor job can have 0 or 1 parameter. A parameter may have spaces. For example, parameters may look like {"par1 par2", "par3", "", "par4 par5"} where "par1 par2" are parameters to the current job. "par3" is the parameter to its parent job. grand parent job has no parameters of its own. "par4 par5" are the parameters to its grandgrandparent job. Note that for a exec job, there can be arguments to the executable. But arguments are not parameters.
    
    Returns:
    
    The job names and parameters of ancestry.
  - formStrRep
```
private void formStrRep()
```
  - toString
```
public java.lang.String toString()
```
    Get the string representation of the job. Each job is identified by its path to the log file relative to the log root dir. The representing string is the concatenation of name-parameter of each of this job's ancestry, separated by the path separator. All special characters are replaced with repEx. Example, grandparent/parent_par1_par2/me_par3.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a String uniquely identifies the job. This assumes job parameters after replacing special characters are enough to distinguish sibling jobs.
  - getStatus
```
Status getStatus()
```
  - ignore
```
void ignore()
```
  - markFail
```
void markFail()
```
  - updateStatus
```
Status updateStatus()
```
    Obtain the status of the task. When the status is being checked, this job or its child may be placed into queue. And a new execution may get started if the current job is finished. All exceptions are caught here and recorded. The whole program is then aborted. There is no waiting since no executable will be started here.
    
    Returns:
    
    The status of the job.
  - updateStatusImpl
```
private void updateStatusImpl()
                       throws java.lang.Exception
```
    Throws:
    
    java.lang.Exception
  - hasSucceededLast
```
protected boolean hasSucceededLast()
                            throws java.lang.Exception
```
    For a resumed run, test if this job has completed in the previous run. If so, the status of this job is updated correspondingly.
    
    Returns:
    
    true if this job has finished successfully in the previous run.
    
    Throws:
    
    java.lang.Exception
  - kill
```
void kill()
```
    Try to stop the job assuming it has not successfully finished.
  - extractTaskName
```
static java.lang.String extractTaskName(java.io.File path)
```
  - debugDump
```
protected java.lang.String debugDump()
```
    Dump the current state of the job.
  - dumpMore
```
protected abstract java.lang.String dumpMore()
```
  - advance
```
protected abstract Status advance()
                           throws java.lang.Exception
```
    Check the current status assuming the last update had status RUNNING.
    
    Returns:
    
    true if the current job has finished.
    
    Throws:
    
    java.lang.Exception
  - terminate
```
protected abstract void terminate()
```
    Forcibly terminate this job.

Class Task

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

normalEx

repEx

nameParSep

stat

name

strRep

param

parent

level

Constructor Detail

Task

Method Detail

getName

getParam

getLevel

fetchAncestry

formStrRep

toString

getStatus

ignore

markFail

updateStatus

updateStatusImpl

hasSucceededLast

kill

extractTaskName

debugDump

dumpMore

advance

terminate