Config (Jobman API)

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

```
class Config
extends java.lang.Object
```
This class reads various configuration files and provides methods to query configurations. All its members and methods are static. The class contains several configuration parameters. A configuration is dynamic if its value can be re-read while jobman program is running. Otherwise it is static, which means any changes after the program starts running don't take effect.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

private static class Config.ExecInfo

Nested Classes
Modifier and Type	Class and Description
`private static class`	`Config.ExecInfo`

Field Summary

Fields
Modifier and Type	Field and Description
`private static java.util.SortedSet<java.lang.String>`	`allJobs` All jobs mentioned in the job list file.
`private static int`	`betweenInvokes` Sleep time, in milliseconds, between the two new process/thread invokes.
`(package private) static java.lang.String`	`cfgDir` The configuration directory.
`private static java.io.File`	`cfgRoot` Configuration directory.
`private static java.io.File`	`dumpFile` The File of the dump file.
`private static java.lang.String`	`dumpFileName` The file flags the important parameters and stage variables should be dumped.
`private static boolean`	`enableDebug` Specify if we want to dump debug details into the master log file.
`private static java.util.Map<java.lang.String,Config.ExecInfo>`	`exeSpec`
`private static java.util.ArrayList<java.lang.String>`	`ignoredErrors` This is the vector of error strings that should be ignored.
`private static java.lang.String`	`ignoreFileName` The file lists error string from executable child jobs that should be ignored.
`private static java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>`	`jobInfo` Job information.
`private static java.lang.String`	`jobListFileName` The configuration file listing specifying all jobs.
`private static java.lang.String`	`jobRankFileName` The configuration file specifying the ranks of jobs.
`private static java.util.SortedSet<java.lang.String>`	`jobsToRun` This lists all jobs to be run (under the top job).
`private static java.util.HashMap<java.lang.String,java.lang.String>`	`jobTypes` Job type look up hash table.
`private static java.io.File`	`killFile` The File of the kill file.
`private static java.lang.String`	`killFileName` The file flags the jobman program should stop running.
`private static java.nio.channels.FileChannel`	`lockChan` The file handle to the lock file.
`private static java.lang.String`	`lockFilePath` The path (absolute or relative to the jobman root directory) to the lock file.
`private static int`	`numParallel` The maximum number of exec jobs running, i.e., the maximum number of parallel running processes invoked by jobman.
`private static java.lang.String`	`optDynamicFileName` The optional configuration file specifying parameters that can be re-read when jobman is running.
`private static java.lang.String`	`optStaticFileName` The optional configuration file specifying parameters that will not be read after jobman starts.
`private static java.io.File`	`pauseFile` The File to the pause file.
`private static java.lang.String`	`pauseFileName` The file flags that the jobman running should pause.
`private static java.nio.channels.FileLock`	`projLock` The file lock for this jobman program run.
`private static int`	`queueLen` The max queue length for each job to be placed before execution.
`private static java.io.File`	`refreshFile` The File of the refresh file.
`private static java.lang.String`	`refreshFileName` The file flags that the dynamic parameters should be re-read.
`(package private) static java.util.TreeSet<java.lang.String>`	`reserved` Reserved keywords not to be used as a task name.
`private static boolean`	`resumeLast` Indicates if the program should start from what was left in the previous run.
`private static java.lang.String`	`root` The absolute path to the home directory of jobman.
`private static int`	`sleepTime` Sleep time, in milliseconds, between two cycles of job status updates.
`private static java.util.Map<java.lang.String,java.lang.Object[]>`	`statMap` Map from each job name to a pair of its specific success string and Boolean if error should be checked.
`private static java.lang.String`	`successString` The default string indicating that a terminal job has finished successfully.
`private static java.lang.String`	`timeFormat` The date time format used in log file.
`private static java.lang.String`	`topJobName` The name of the top most job.
`private static java.lang.String`	`toStopString` The string indicating that the job requests all its sibling jobs should be skipped.

Constructor Summary

Constructors
Modifier Constructor and Description

private Config()
All members are static.

Constructors
Modifier	Constructor and Description
`private`	`Config()` All members are static.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) static java.lang.String`	`debugDump()` Dump all configuration parameters used in the jobman program.
`private static void`	`dynamicConfig()` reload all the key-value settings that are dynamically configurable.
`private static java.lang.String`	`errInCfg(java.lang.String fileName, java.lang.String l)` Formate error message.
`(package private) static int`	`getBetweenInvokes()` Get the sleep time, in milliseconds, between two invocations of new processes or threads.
`private static java.util.ArrayList<java.lang.String>`	`getDescendants(java.lang.String jobName)` Get all descendants of a job.
`(package private) static boolean`	`getEnableDebug()`
`(package private) static boolean`	`getExeCatchStdErr(java.lang.String job)`
`(package private) static boolean`	`getExeCatchStdOut(java.lang.String job)`
`(package private) static boolean`	`getExecCheckErr(java.lang.String job)`
`(package private) static boolean`	`getExecCheckLog(java.lang.String job)`
`(package private) static int`	`getExecParallels(java.lang.String job)`
`(package private) static int`	`getExecRank(java.lang.String job)`
`(package private) static java.lang.String`	`getExecSuccess(java.lang.String job)`
`(package private) static java.util.ArrayList<java.lang.String>`	`getIgnoredErrors()` Get list of error messages that should be ignored.
`(package private) static java.util.ArrayList<java.lang.String>`	`getJobInfo(java.lang.String name)` Get information on a job.
`(package private) static java.lang.String`	`getJobType(java.lang.String name)` Get the type of a given job.
`(package private) static int`	`getNumParallel()` Get the max number of processes to be run in parallel.
`(package private) static int`	`getQueueLen()` Get the max number of jobs to be placed in the queue.
`(package private) static boolean`	`getResumeLast()` Get if jobman should start from where last run ended.
`(package private) static java.lang.String`	`getRoot()` Get jobman home directory.
`(package private) static java.lang.String`	`getSuccessString(java.lang.String taskName)` Get the string indicating a job has been completed successfully.
`(package private) static java.lang.String`	`getTimeFormat()` Get the date time format used in the master log file.
`(package private) static java.lang.String`	`getToStopString()` Get the string indicating a job has been completed successfully and request skip all its sibling jobs.
`(package private) static void`	`init(java.lang.String rootPath, java.lang.String topName)` Initialize the configuration system.
`private static boolean`	`isParent(java.lang.String jobName)` Check if a job is a parent or terminal job.
`private static void`	`oneLineFromJobList(java.lang.String l)` Process one line in the job list file.
`private static java.util.Properties`	`readConfigFile(java.lang.String fileName)` Read files consisting of lines of key-value pairs.
`private static void`	`readIgnored()` Read error messages that should be ignored.
`private static java.util.ArrayList<java.lang.String>`	`readJobFile(java.lang.String fileName)` Read a configuration file and insert the lines (excluding comments) into the passed in vector.
`private static void`	`readJobList()` Read the job list file.
`private static void`	`readLeafList()` Read the job rank file and stored the job ranking into Schedule class variables.
`(package private) static void`	`refresh()` Process the configuration files.
`(package private) static void`	`release()` Release the lock file held by the jobman program.
`private static void`	`reloadSettings()` Reload all dynamically configurable settings.
`private static void`	`staticConfig()` Load the static configurations from the file.
`private static java.util.ArrayList<java.lang.String>`	`substitute(java.util.ArrayList<java.lang.String> lines, java.util.Map<java.lang.String,java.lang.String> variables)`
`private static void`	`validate()` Validate the job configurations.

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

- Field Detail
  - reserved
```
static final java.util.TreeSet<java.lang.String> reserved
```
    Reserved keywords not to be used as a task name.
  - cfgDir
```
static final java.lang.String cfgDir
```
    The configuration directory.
    
    See Also:
    
    Constant Field Values
  - jobListFileName
```
private static final java.lang.String jobListFileName
```
    The configuration file listing specifying all jobs. This must exist.
    
    See Also:
    
    Constant Field Values
  - jobRankFileName
```
private static final java.lang.String jobRankFileName
```
    The configuration file specifying the ranks of jobs. It is an optional file.
    
    See Also:
    
    Constant Field Values
  - optDynamicFileName
```
private static final java.lang.String optDynamicFileName
```
    The optional configuration file specifying parameters that can be re-read when jobman is running.
    
    See Also:
    
    Constant Field Values
  - optStaticFileName
```
private static final java.lang.String optStaticFileName
```
    The optional configuration file specifying parameters that will not be read after jobman starts.
    
    See Also:
    
    Constant Field Values
  - pauseFileName
```
private static final java.lang.String pauseFileName
```
    The file flags that the jobman running should pause.
    
    See Also:
    
    Constant Field Values
  - refreshFileName
```
private static final java.lang.String refreshFileName
```
    The file flags that the dynamic parameters should be re-read.
    
    See Also:
    
    Constant Field Values
  - killFileName
```
private static final java.lang.String killFileName
```
    The file flags the jobman program should stop running.
    
    See Also:
    
    Constant Field Values
  - dumpFileName
```
private static final java.lang.String dumpFileName
```
    The file flags the important parameters and stage variables should be dumped.
    
    See Also:
    
    Constant Field Values
  - ignoreFileName
```
private static final java.lang.String ignoreFileName
```
    The file lists error string from executable child jobs that should be ignored. Each line contains one error string. If the error message from an executable contains an error string in the list, it will be ignored.
    
    See Also:
    
    Constant Field Values
  - root
```
private static java.lang.String root
```
    The absolute path to the home directory of jobman.
  - cfgRoot
```
private static java.io.File cfgRoot
```
    Configuration directory.
    
    See Also:
    
    config
  - pauseFile
```
private static java.io.File pauseFile
```
    The File to the pause file.
    
    See Also:
    
    pause
  - refreshFile
```
private static java.io.File refreshFile
```
    The File of the refresh file.
    
    See Also:
    
    refresh
  - killFile
```
private static java.io.File killFile
```
    The File of the kill file.
    
    See Also:
    
    kill
  - dumpFile
```
private static java.io.File dumpFile
```
    The File of the dump file.
    
    See Also:
    
    dump
  - lockChan
```
private static java.nio.channels.FileChannel lockChan
```
    The file handle to the lock file.
    
    See Also:
    
    lopa
  - projLock
```
private static java.nio.channels.FileLock projLock
```
    The file lock for this jobman program run.
    
    See Also:
    
    chan
  - successString
```
private static java.lang.String successString
```
    The default string indicating that a terminal job has finished successfully. This string should be output by each terminal job to signal its completion, unless the user specifies otherwise in leafs.cfg. The string should contain only alphanumeric characters or the underscore '_'. This configuration is static.
  - statMap
```
private static final java.util.Map<java.lang.String,java.lang.Object[]> statMap
```
    Map from each job name to a pair of its specific success string and Boolean if error should be checked.
  - toStopString
```
private static java.lang.String toStopString
```
    The string indicating that the job requests all its sibling jobs should be skipped. Its sibling jobs are those that share the same parent job. This configuration is static.
  - timeFormat
```
private static java.lang.String timeFormat
```
    The date time format used in log file.
  - ignoredErrors
```
private static final java.util.ArrayList<java.lang.String> ignoredErrors
```
    This is the vector of error strings that should be ignored. This configuration is static.
    
    See Also:
    
    ignore
  - lockFilePath
```
private static java.lang.String lockFilePath
```
    The path (absolute or relative to the jobman root directory) to the lock file. This configuration is static.
  - resumeLast
```
private static boolean resumeLast
```
    Indicates if the program should start from what was left in the previous run. If true, all jobs that were successful according to the log files are skipped. This configuration is static.
  - numParallel
```
private static int numParallel
```
    The maximum number of exec jobs running, i.e., the maximum number of parallel running processes invoked by jobman. This configuration is dynamic.
  - sleepTime
```
private static int sleepTime
```
    Sleep time, in milliseconds, between two cycles of job status updates. This configuration is dynamic.
  - betweenInvokes
```
private static int betweenInvokes
```
    Sleep time, in milliseconds, between the two new process/thread invokes. This configuration is dynamic.
  - enableDebug
```
private static boolean enableDebug
```
    Specify if we want to dump debug details into the master log file. This configuration is dynamic.
  - queueLen
```
private static int queueLen
```
    The max queue length for each job to be placed before execution. This configuration is dynamic.
  - jobTypes
```
private static final java.util.HashMap<java.lang.String,java.lang.String> jobTypes
```
    Job type look up hash table. Both of its key and value are strings. A key is a job name and its value is the type of the job (node, exec, etc).
  - allJobs
```
private static final java.util.SortedSet<java.lang.String> allJobs
```
    All jobs mentioned in the job list file. It may contain jobs not to be run by jobman. This is used to verify that all jobs are specified. Each element in the set is a string representing the job name.
  - jobInfo
```
private static final java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> jobInfo
```
    Job information. It is a map whose keys are job names as String, and whose values depend on job type. (See method oneLineFromJobList().) For job of parent types, the value is a vector of child job names. Each Vector (for child job) is ordered according to user's specification in config file. For a exec job, it is the executable including the arguments.
  - topJobName
```
private static java.lang.String topJobName
```
    The name of the top most job.
  - jobsToRun
```
private static final java.util.SortedSet<java.lang.String> jobsToRun
```
    This lists all jobs to be run (under the top job).
  - exeSpec
```
private static final java.util.Map<java.lang.String,Config.ExecInfo> exeSpec
```
- Constructor Detail
  - Config
```
private Config()
```
    All members are static. No instantiation of the class is necessary.
- Method Detail
  - init
```
static void init(java.lang.String rootPath,
                 java.lang.String topName)
          throws java.lang.Exception
```
    Initialize the configuration system. All user configuration files are read. The logging system job dependences are also initialized.
    
    Parameters:
    
    rootPath - The home directory of the program.
    
    topName - The top most job to be run.
    
    Throws:
    
    java.lang.Exception
  - reloadSettings
```
private static void reloadSettings()
                            throws java.lang.Exception
```
    Reload all dynamically configurable settings.
    
    Throws:
    
    java.lang.Exception
  - release
```
static void release()
```
    Release the lock file held by the jobman program. A lock file is used by the jobman program to avoid two jobman programs running at the same time.
  - refresh
```
static void refresh()
             throws java.lang.Exception
```
    Process the configuration files. The communication between the user and the jobman program is file based. The user creates a file of particular name to request certain action from the jobman program. Once the action is carried out, the communicate files are deleted. This function checks all the communication files and perform actions as instructed. For example, reload the values for those parameters that are dynamically configurable, including job list and job dependences. If there is a problem, the program should be in pause mode and let user correct.
    
    Throws:
    
    java.lang.Exception
  - readConfigFile
```
private static java.util.Properties readConfigFile(java.lang.String fileName)
                                            throws java.lang.Exception
```
    Read files consisting of lines of key-value pairs.
    
    Parameters:
    
    fileName - The name of the file in the "cfg" directory.
    
    Throws:
    
    java.lang.Exception
  - staticConfig
```
private static void staticConfig()
                          throws java.lang.Exception
```
    Load the static configurations from the file.
    
    Throws:
    
    java.lang.Exception
  - dynamicConfig
```
private static void dynamicConfig()
                           throws java.lang.Exception
```
    reload all the key-value settings that are dynamically configurable.
    
    Throws:
    
    java.lang.Exception
  - getSuccessString
```
static java.lang.String getSuccessString(java.lang.String taskName)
```
    Get the string indicating a job has been completed successfully. It could be null, which means log file is not used as a success criterion.
  - getToStopString
```
static java.lang.String getToStopString()
```
    Get the string indicating a job has been completed successfully and request skip all its sibling jobs.
  - getTimeFormat
```
static java.lang.String getTimeFormat()
```
    Get the date time format used in the master log file.
  - getNumParallel
```
static int getNumParallel()
```
    Get the max number of processes to be run in parallel.
  - getQueueLen
```
static int getQueueLen()
```
    Get the max number of jobs to be placed in the queue.
  - getBetweenInvokes
```
static int getBetweenInvokes()
```
    Get the sleep time, in milliseconds, between two invocations of new processes or threads.
  - getIgnoredErrors
```
static java.util.ArrayList<java.lang.String> getIgnoredErrors()
```
    Get list of error messages that should be ignored.
    
    Returns:
    
    The vector of strings of error messages to be ignored. Any lines in the error output from a terminal job executed in a separate thread or process will be ignored.
  - getEnableDebug
```
static boolean getEnableDebug()
```
    Returns:
    
    True if detailed debug should be logged.
  - getResumeLast
```
static boolean getResumeLast()
```
    Get if jobman should start from where last run ended.
    
    Returns:
    
    True if the jobman should start from where it left in the last run. This will not delete old log files but use them to detect the status of the previous run.
  - readIgnored
```
private static void readIgnored()
                         throws java.lang.Exception
```
    Read error messages that should be ignored.
    
    Throws:
    
    java.lang.Exception
  - readJobFile
```
private static java.util.ArrayList<java.lang.String> readJobFile(java.lang.String fileName)
                                                          throws java.lang.Exception
```
    Read a configuration file and insert the lines (excluding comments) into the passed in vector. A comment line starts with '#'. A comment block is also ignored. A comment block starts with a line starting '{' and ends with a line starting '}'.
    
    Parameters:
    
    fileName - The name of the configuration file.
    
    Returns:
    
    lThe vector of strings of job specifications.
    
    Throws:
    
    java.lang.Exception
  - substitute
```
private static java.util.ArrayList<java.lang.String> substitute(java.util.ArrayList<java.lang.String> lines,
                                                                java.util.Map<java.lang.String,java.lang.String> variables)
```
  - readLeafList
```
private static void readLeafList()
                          throws java.lang.Exception
```
    Read the job rank file and stored the job ranking into Schedule class variables. A sample file may look like this:
```
 # job rank parallels check_log check_error success
 job_a 10 2 true true Job completed
 job_b -5 5 true false This is done
 job_c 2 0 false true default job_d 4
 
```
    Each line is an executable job specific setting. Higher rank has higher priority. A negative parallels mean no limit on parallel processes to run. The zero parallels means following the default parallel setting. If check_log is true, then log file will not be generated.
    Throws:
    
    java.lang.Exception
  - getExecRank
```
static int getExecRank(java.lang.String job)
```
  - getExecParallels
```
static int getExecParallels(java.lang.String job)
```
  - getExecCheckLog
```
static boolean getExecCheckLog(java.lang.String job)
```
  - getExecCheckErr
```
static boolean getExecCheckErr(java.lang.String job)
```
  - getExeCatchStdOut
```
static boolean getExeCatchStdOut(java.lang.String job)
```
  - getExeCatchStdErr
```
static boolean getExeCatchStdErr(java.lang.String job)
```
  - getExecSuccess
```
static java.lang.String getExecSuccess(java.lang.String job)
```
  - readJobList
```
private static void readJobList()
                         throws java.lang.Exception
```
    Read the job list file.
    
    Throws:
    
    java.lang.Exception
  - oneLineFromJobList
```
private static void oneLineFromJobList(java.lang.String l)
                                throws java.lang.Exception
```
    Process one line in the job list file. From the line, the function extracts the job type and relevant info. It saves into member hashtable jobInfo member. It saves dependencies into class Depend.
    
    Throws:
    
    java.lang.Exception
  - errInCfg
```
private static java.lang.String errInCfg(java.lang.String fileName,
                                         java.lang.String l)
```
    Formate error message.
    
    Parameters:
    
    fileName - The source file name.
    
    l - The error line.
    
    Returns:
    
    A string suitable to be written into the log file.
  - getJobType
```
static java.lang.String getJobType(java.lang.String name)
```
    Get the type of a given job.
    
    Parameters:
    
    name - The name of the job.
    
    Returns:
    
    The type of the job.
  - getJobInfo
```
static java.util.ArrayList<java.lang.String> getJobInfo(java.lang.String name)
```
    Get information on a job.
    
    Parameters:
    
    name - The name of a job.
    
    Returns:
    
    The vector of strings of job information. Its structure depends on job type. For job of parent type, it is the vector of strings of child job names, ordered in according to user's preference in job list config file. For a exec job, it is the vector of strings consisting of the executable and arguments.
  - getRoot
```
static java.lang.String getRoot()
```
    Get jobman home directory.
    
    Returns:
    
    The absolute path to the home directory of jobman.
  - debugDump
```
static java.lang.String debugDump()
```
    Dump all configuration parameters used in the jobman program.
  - getDescendants
```
private static java.util.ArrayList<java.lang.String> getDescendants(java.lang.String jobName)
```
    Get all descendants of a job.
    
    Parameters:
    
    jobName - The name of a job.
    
    Returns:
    
    A vector of strings of jobs which are descendants of jobName. The top job jobName itself is also in the list. The order of the descendant jobs is not guaranteed.
  - isParent
```
private static boolean isParent(java.lang.String jobName)
```
    Check if a job is a parent or terminal job.
    
    Parameters:
    
    jobName - The name of a job.
    
    Returns:
    
    true if the jobName contains other jobs as children.
  - validate
```
private static void validate()
```
    Validate the job configurations.

Class Config

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

reserved

cfgDir

jobListFileName

jobRankFileName

optDynamicFileName

optStaticFileName

pauseFileName

refreshFileName

killFileName

dumpFileName

ignoreFileName

root

cfgRoot

pauseFile

refreshFile

killFile

dumpFile

lockChan

projLock

successString

statMap

toStopString

timeFormat

ignoredErrors

lockFilePath

resumeLast

numParallel

sleepTime

betweenInvokes

enableDebug

queueLen

jobTypes

allJobs

jobInfo

topJobName

jobsToRun

exeSpec

Constructor Detail

Config

Method Detail

init

reloadSettings

release

refresh

readConfigFile

staticConfig

dynamicConfig

getSuccessString

getToStopString

getTimeFormat

getNumParallel

getQueueLen

getBetweenInvokes

getIgnoredErrors

getEnableDebug

getResumeLast

readIgnored

readJobFile

substitute

readLeafList

getExecRank

getExecParallels

getExecCheckLog

getExecCheckErr

getExeCatchStdOut

getExeCatchStdErr

getExecSuccess

readJobList

oneLineFromJobList

errInCfg

getJobType

getJobInfo

getRoot