org.peace_tools.workspace
Class Job

java.lang.Object
  org.peace_tools.workspace.JobBase
      org.peace_tools.workspace.Job

public class Job
extends JobBase

This class corresponds to a "Job" element in a PEACE work space XML data. This class encapsulates the core information associated with a Job. This class serves merely as a read-only type class that is created when a new job is run. The data is persisted in the XML work space for future reference so that users can determine jobs that were scheduled and check on status of long-running jobs.

Nested Class Summary

Nested classes/interfaces inherited from class org.peace_tools.workspace.JobBase

JobBase.JobStatusType

Field Summary

private int	cpusPerNode The number of CPUS per Nodes (on a cluster) that were requested for running this job.
private java.lang.String	description A user defined description for this job.
private java.util.ArrayList<Filter>	filters The list of filters configured by the user for this job.
private java.util.ArrayList<Heuristic>	heuristics The list of heuristics configured by the user for this job.
private javax.xml.datatype.XMLGregorianCalendar	lastUpdateTimestamp The time stamp value of the last time the status of this job was updated.
private int	maxRunTime The total wall clock run time to be reserved for this job when submitting via a PBS system.
private int	memory The peak memory to be reserved for this job when submitting via a PBS system.
private java.lang.Thread	monitor A transient (not persistent) reference to the monitor thread for this job (if any).
private int	nodes The number of nodes on a cluster that were requested for running this job.
private java.lang.String	path The path to the directory on the server (may it be local or remote) where the files corresponding to this job are stored.
private int[]	progressInfo A transient (not persisted) progress information about the job.
private javax.xml.datatype.XMLGregorianCalendar	startTimestamp The time when this job was actually created and queued to run on a server.

Fields inherited from class org.peace_tools.workspace.JobBase

jobID, runtime, serverID, status

Constructor Summary

Job(java.lang.String jobID, java.lang.String description, java.lang.String serverID, java.lang.String path, int nodes, int cpusPerNode, int memory, int maxRunTime, java.util.ArrayList<Heuristic> heuristics, java.util.ArrayList<Filter> filters)
Constructor to create a Job object with the fixed value fields initialized to specific values.

Method Summary

static Job	create(org.w3c.dom.Element jobNode) Helper method to utilize data from a DOM tree to create a suitable Job entry.
int	getCPUsPerNode() Obtain the number of CPUs on each node that were requested for running this job.
java.lang.String	getDescription() Obtain the user supplied description for this this job.
java.util.ArrayList<Filter>	getFilterList() Obtain the list of filters that were used to improve quality of clustering.
java.lang.String	getFiltersCmdLine() Command line for PEACE clustering engine to configure filters.
java.util.ArrayList<Heuristic>	getHeuristicList() Obtain the list of heuristics that were used to accelerate the process of constructing the MST.
java.lang.String	getHeuristicsCmdLine() Command line for PEACE clustering engine to configure heuristics.
javax.xml.datatype.XMLGregorianCalendar	getLastUpdateTimestamp() Returns the last time the status of this job was set/changed.
int	getMaxRunTime() Obtain the total time to be requested for this job.
int	getMemory() Obtain the memory to be requested for this job.
java.lang.Thread	getMonitor() Obtain the job monitoring thread (if any)
int	getNodes() Obtain the number of nodes that were requested for running this job.
java.lang.String	getPath() Obtain the system generated directory where the output files for this job are stored on the server.
int[]	getProgressInfo() Obtain the current progress information status for this job.
javax.xml.datatype.XMLGregorianCalendar	getStartTimestamp() Obtain the timestamp indicating when the job actually started running on the server.
void	marshall(org.w3c.dom.Element jobList) Method to marshall the data stored in this object to become part of a DOM tree element passed in.
void	marshall(java.io.PrintWriter out) Method to marshall the data stored in this object directly to a XML fragment.
private static java.util.ArrayList<Filter>	parseFilterChain(org.w3c.dom.Element jobNode) Helper method to unmarshall the filter list into an in-memory array list.
private static java.util.ArrayList<Heuristic>	parseHeuristicChain(org.w3c.dom.Element jobNode) Helper method to unmarshall the heuristic list into an in-memory array list.
void	setDescription(java.lang.String desc) Set a description for this job.
private void	setLastUpdateTime() This is a helper method that is used to set the lastUpdateTimestamp to the current system time.
void	setMonitor(java.lang.Thread monitor) Set the monitoring thread for this Job.
void	setPath(java.lang.String path) Set the path where the files for this job are located.
void	setProgress(int estsAnalyzed, int totalEstCount) Set the progress status for this job.
void	setStartTimestamp(java.util.GregorianCalendar timestamp) This method can be used to explicitly set the time stamp when this job actually started running on the server.
void	setStatus(JobBase.JobStatusType status) Change the status for this job.
java.lang.String	toCmdLine() Return the information in the form of a partial PEACE command line parameter.
java.lang.String	toString()

Methods inherited from class org.peace_tools.workspace.JobBase

getJobID, getRunTime, getServerID, getStatus, isDone, setRunTime

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

description

private java.lang.String description

A user defined description for this job. This description is set when a new job is scheduled and persisted in the work space configuration for future references.

path

private java.lang.String path

The path to the directory on the server (may it be local or remote) where the files corresponding to this job are stored.

nodes

private int nodes

The number of nodes on a cluster that were requested for running this job.

cpusPerNode

private int cpusPerNode

The number of CPUS per Nodes (on a cluster) that were requested for running this job.

memory

private int memory

The peak memory to be reserved for this job when submitting via a PBS system. This value is in giga bytes.

maxRunTime

private int maxRunTime

The total wall clock run time to be reserved for this job when submitting via a PBS system. The value is in hours.

startTimestamp

private javax.xml.datatype.XMLGregorianCalendar startTimestamp

The time when this job was actually created and queued to run on a server. This value does not have a bearing on the runtime of a job. This value is persisted for future reference on long running jobs.

lastUpdateTimestamp

private javax.xml.datatype.XMLGregorianCalendar lastUpdateTimestamp

The time stamp value of the last time the status of this job was updated. This value is periodically updated until the job completes running.

heuristics

private java.util.ArrayList<Heuristic> heuristics

The list of heuristics configured by the user for this job. These heuristics are used to accelerate the MST generation algorithm.

filters

private java.util.ArrayList<Filter> filters

The list of filters configured by the user for this job. These filters are used to weed out fragments that may interfer with clustering and reduce overall quality of clustering.

progressInfo

private transient int[] progressInfo

A transient (not persisted) progress information about the job. The first entry is the number of ESTs that have been analyzed and the second entry is the total number of ESTs being analyzed. This information is useful for GUI's to display some progress information is desired. This value is periodically updated in the run() method if the job is in QUEUED or RUNNING status.

monitor

private transient java.lang.Thread monitor

A transient (not persistent) reference to the monitor thread for this job (if any). This value is set whenever a new monitor thread is created for this job. The reference is reset when the monitor thread is stopped. The monitoring thread is actually implemented by org.peace_tools.core.JobMonitor class.

Constructor Detail

Job

public Job(java.lang.String jobID,
           java.lang.String description,
           java.lang.String serverID,
           java.lang.String path,
           int nodes,
           int cpusPerNode,
           int memory,
           int maxRunTime,
           java.util.ArrayList<Heuristic> heuristics,
           java.util.ArrayList<Filter> filters)

Constructor to create a Job object with the fixed value fields initialized to specific values.

Parameters:

jobID - The workspace-wide unique, generated job ID for this job. The jobID is generated via a call to JobList.reserveJobID() method. This is a valid string (typically in the form job####)

description - A user-supplied description for this job entry. This maybe an empty string (but cannot be null).

serverID - The ID of the server on which this job is running. This is a cross reference ID of a Server configured in this workspace.

path - The directory on the server where the data for this job is stored.

nodes - The number of compute nodes that were requested on a cluster for running this job. This value must be at least 1.

cpusPerNode - The number of CPUs on each node that were requested for this job. This value must be at least 1.

memory - The total memory (sum of all memory used by all processes, in MB) that was allocated for this job.

maxRunTime - The maximum runtime (in hours) that was assigned for this job.

heuristics - The list of heuristics that were used to accelerate the MST generation algorithm.

filters - The list of filters that were used to filter out short ESTs or ESTs with low complexity sections to ensure that the resultant clustering is high quality.

Method Detail

create

public static Job create(org.w3c.dom.Element jobNode)
                  throws java.lang.Exception

Helper method to utilize data from a DOM tree to create a suitable Job entry. This method is typically used to create a suitable Job entry when loading a Work space into the GUI.

Parameters:

jobNode - The DOM element to be used for creating the Job entry and populating with the needed data.

Returns:

The newly created job entry based on the DOM data.

Throws:

java.lang.Exception - This method throws an exception when errors occur during reading and processing elements from the DOM node.

parseHeuristicChain

private static java.util.ArrayList<Heuristic> parseHeuristicChain(org.w3c.dom.Element jobNode)
                                                           throws java.lang.Exception

Helper method to unmarshall the heuristic list into an in-memory array list. This is a helper method that is invoked from the the create() method to unmarshall the XML DOM tree corresponding to the heuristic list node into suitable in-memory classes for further processing.

Parameters:

jobNode - The top-level job node from where the heuristic chain element is to be extracted and processed.

Returns:

An array list containing a list of Heuristic objects.

Throws:

java.lang.Exception - This method throws an exception when errors occur during reading and processing elements from the DOM node.

parseFilterChain

private static java.util.ArrayList<Filter> parseFilterChain(org.w3c.dom.Element jobNode)
                                                     throws java.lang.Exception

Helper method to unmarshall the filter list into an in-memory array list. This is a helper method that is invoked from the the create() method to unmarshall the XML DOM tree corresponding to the filter list node into suitable in-memory classes for further processing.

Parameters:

jobNode - The top-level job node from where the filter chain element is to be extracted and processed.

Returns:

An array list containing the list of filter objects in the filter chain.

Throws:

java.lang.Exception - This method throws an exception when errors occur during reading and processing elements from the DOM node.

getDescription

public java.lang.String getDescription()

Obtain the user supplied description for this this job. The value is set when new jobs are scheduled. The description is persisted in the work space configuration file and loaded when a work space is opened in the GUI.

Returns:

This method returns the user supplied description set for this job.

setDescription

public void setDescription(java.lang.String desc)

Set a description for this job. The description is persisted in the work space configuration file and loaded when a work space is opened in the GUI.

Parameters:

desc -

getPath

public java.lang.String getPath()

Obtain the system generated directory where the output files for this job are stored on the server. This value is set when new jobs are scheduled. The path for the job is persisted in the work space configuration file and loaded when a work space is opened in the GUI.

Returns:

This method returns the directory where the files for this job are located.

setPath

public void setPath(java.lang.String path)

Set the path where the files for this job are located.

Parameters:

path - The path where the files for this job are located.

getNodes

public int getNodes()

Obtain the number of nodes that were requested for running this job.

Returns:

The number of nodes that were requested for running this job.

getCPUsPerNode

public int getCPUsPerNode()

Obtain the number of CPUs on each node that were requested for running this job.

Returns:

The number of CPUs per node that were requested for running this job.

getMemory

public int getMemory()

Obtain the memory to be requested for this job.

Returns:

The memory to be requested for this job. This value is in Gigabytes.

getMaxRunTime

public int getMaxRunTime()

Obtain the total time to be requested for this job. This method must be used to determine the maximum run time to be requested when submitting this job via a job scheduling system.

Returns:

The maximum wall clock time to be requested when submitting this job via PBS. This value is in hours.

setLastUpdateTime

private void setLastUpdateTime()

This is a helper method that is used to set the lastUpdateTimestamp to the current system time.

setStatus

public void setStatus(JobBase.JobStatusType status)

Change the status for this job. This method also sets the last update time stamp.

Overrides:

setStatus in class JobBase

Parameters:

status - The new status value to be set for this job.

getLastUpdateTimestamp

public javax.xml.datatype.XMLGregorianCalendar getLastUpdateTimestamp()

Returns the last time the status of this job was set/changed.

Returns:

The time stamp when the status of this job was last set.

setStartTimestamp

public void setStartTimestamp(java.util.GregorianCalendar timestamp)

This method can be used to explicitly set the time stamp when this job actually started running on the server.

Parameters:

timestamp - The timestamp when the job actually started running on the server. This information is typically determined from the output logs generated by the job.

getStartTimestamp

public javax.xml.datatype.XMLGregorianCalendar getStartTimestamp()

Obtain the timestamp indicating when the job actually started running on the server.

Returns:

The timestamp when the job started running. If the job has not yet started running, then this method returns null.

getHeuristicsCmdLine

public java.lang.String getHeuristicsCmdLine()

Command line for PEACE clustering engine to configure heuristics.

This method can be used to obtain the heuristic information in the form of command line parameters that can be readily passed to the PEACE clustering engine. The command line parameters are used to configure the clustering engine to suit the configuration setup by the user for this job.

Note: The return value of this method must be ignored if this call is being made in conjunction with the two pass d2 analyzer.

Returns:

The command line (to correspondingly setup the heuristics) to be passed to the PEACE clustering engine.

getFiltersCmdLine

public java.lang.String getFiltersCmdLine()

Command line for PEACE clustering engine to configure filters. This method can be used to obtain the filters information in the form of command line parameters that can be readily passed to the PEACE clustering engine. The command line parameters are used to configure the filters used by the clustering engine to mirror the configuration setup by the user for this job.

Returns:

The command line (to correspondingly setup the filters) to be passed to the PEACE clustering engine.

toCmdLine

public java.lang.String toCmdLine()

Return the information in the form of a partial PEACE command line parameter. This method can be used to obtain the information needed to generate the MST and clusters based on the supplied information in the form of a command line parameter.

Returns:

Return the information as a command line to be passed to the PEACE clustering engine.

setProgress

public void setProgress(int estsAnalyzed,
                        int totalEstCount)

Set the progress status for this job. This method generates notifications to all registered workspace listeners.

Parameters:

estsAnalyzed - The number of ESTs that have been analyzed.

totalEstCount - The total number of ESTs to be analyzed.

getProgressInfo

public int[] getProgressInfo()

Obtain the current progress information status for this job.

Note: The progress information returned may be -1, -1 if the progress information is not known.

Returns:

The progress information for the job. The first entry is the number of ESTs analyzed thus far and the second entry is the total number of ESTs to be analyzed.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getHeuristicList

public java.util.ArrayList<Heuristic> getHeuristicList()

Obtain the list of heuristics that were used to accelerate the process of constructing the MST. Specifically many of these heuristics accelerate the frame-word analyzer that was used to build the MST.

Returns:

The list of heuristics that were used to acclerate the MST construction process.

getFilterList

public java.util.ArrayList<Filter> getFilterList()

Obtain the list of filters that were used to improve quality of clustering. Specifically the filters weed out ESTs that are known to interfere with clustering and deteriorate overall quality of results.

Returns:

The list of filters hat were used to improve quality of clustering.

marshall

public final void marshall(org.w3c.dom.Element jobList)

Method to marshall the data stored in this object to become part of a DOM tree element passed in. This method assumes that the element passed in corresponds to the parent JobList node in the DOM tree.

Parameters:

jobList - The DOM element corresponding to the "JobList" node that contains this entry.

marshall

public final void marshall(java.io.PrintWriter out)

Method to marshall the data stored in this object directly to a XML fragment. The XML fragment is guaranteed to be compatible with the PEACE work space configuration data.

Parameters:

out - The stream to which the XML must be serialized.

setMonitor

public void setMonitor(java.lang.Thread monitor)

Set the monitoring thread for this Job. This method sets up the monitoring thread for this job. It also broadcasts an update event to all workspace listeners. This enables any GUI components to update their display.

Parameters:

monitor - The monitoring thread for this job. If this parameter is null, then the job monitor thread is cleared.

getMonitor

public java.lang.Thread getMonitor()

Obtain the job monitoring thread (if any)

Returns:

The job monitoring thread associated with this job. If a monitor thread is not set, then this method returns null.