org.peace_tools.workspace
Class Workspace

java.lang.Object
  org.peace_tools.workspace.Workspace

public class Workspace
extends java.lang.Object

The top-level Workspace class that stores and manages all the data associated with a PEACE Workspace. Note that the purpose of the Workspace class is to encapsulate and manage the data associated with the workspace and not to display it. Display of Workspace data is delegated to other classes that focus on presenting a suitable "view" of the data. This design follows the Model-View-Controller (MVC) design pattern.

Currently, each PEACE GUI instance operates only with a single Workspace. Consequently to enfore the use of a single, unique Workspace object, this class has been designed using the Singleton design pattern.

Field Summary

private ClassifierList	classifierList The list of data base classifiers that are used to classify and group ESTs obtained from different data bases.
private javax.xml.datatype.XMLGregorianCalendar	creationTimestamp The time stamp when this workspace was created.
private java.util.ArrayList<DataSet>	dataSetList The list of data sets that have been configured for use in this work space.
private JobList	jobList The list of Job classes that have been configured for use in this work space.
private java.util.ArrayList<WorkspaceListener>	listeners The list of listeners that are currently registered to receive notifications on changes that have occured to various entries in the workspace.
private long	seqCounter Sequence counter that is maintained on a per-work space basis to generate unique/valid IDs for each new entry that is added to this workspace.
private ServerList	serverList The list of Server classes that have been configured for use in this work space.
private static Workspace	workspace The process-wide, unique instance of the workspace object.
private java.lang.String	workspaceDirectory The directory where all the files associated with this workpsace are stored.

Constructor Summary

private

Workspace() The default constructor.

Method Summary

void	addDataSet(DataSet dataSet) Method to add a new data set to the workspace.
void	addWorkspaceListener(WorkspaceListener listener) Add a workspace listener to receive change notification events from this workspace.
static Workspace	createDefault(java.lang.String directory) Method to create default work space met data in a given directory.
void	fireWorkspaceChanged(WorkspaceEvent event) Utility method to notify all the listeners about a change to the Workspace.
static Workspace	get() Method to get a reference to the process-wide, unique instance of the PEACE workspace.
ClassifierList	getClassifierList() Obtain the classifier list set for this work space.
MSTClusterData	getClusterData(java.lang.String jobID) Obtain the MSTClusterData entry for a given job ID.
java.util.ArrayList<DataSet>	getDataSets() Obtain the list of data sets associated with this workspace.
java.lang.String	getDirectory() Obtain the directory where all the files pertaining to this workspace are stored by default.
JobList	getJobList() Obtain the JobList that encapsulates the list of Jobs that have been configured in this workspace.
MSTData	getMSTData(java.lang.String jobID) Obtain the MSTData entry for a given job ID.
ServerList	getServerList() Obtain the ServerList that encapsulates the list of Servers that have been configured in this workspace.
static java.lang.String	getWorkspaceFile(java.lang.String directory) Method to provide consistent name for the PEACE workspace file name so that the file names are consistently used throughout.
private static Workspace	loadCoreWorkspaceData(org.w3c.dom.Document workspaceData, java.lang.String directory) Helper method to simply load the top-level Directory for the Workspace and the creation time stamp for this workspace from a DOM document.
org.w3c.dom.Document	marshall() Obtain a new DOM document representing the data associated with the current work space configuration information.
void	marshall(java.io.PrintWriter out) Method to marshall the data stored in this object directly to a XML fragment.
void	removeDataSet(DataSet dataSet) Method to add a new data set to the workspace.
void	removeWorkspaceListener(WorkspaceListener listener) Remove a workspace listener from the listeners to receive notification events from this workspace.
java.lang.String	reserveID() Reserves the next sequence number for use in a data set.
void	saveWorkspace() Save the current work space configuration information.
void	saveWorkspaceViaDOM() This method can be used to save the work space configuration to disk.
java.lang.String	toString() Provides a string of the form Workspace (../path) to display some workspace related information to the user.
static Workspace	useWorkspace(java.lang.String directory) Method to load workspace data from a given directory.
protected static void	validate(org.w3c.dom.Document workspace) This is a helper method that can be used to validate a Workspace DOM tree against the PEACE schema.

Methods inherited from class java.lang.Object

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

Field Detail

workspace

private static Workspace workspace

The process-wide, unique instance of the workspace object. This object contains all the necessary information regarding the workspace that is being currently used by the PEACE GUI. If a valid workspace is currently unavailable, then this object will be null.

workspaceDirectory

private java.lang.String workspaceDirectory

The directory where all the files associated with this workpsace are stored. This value is set when a workspace is created or when a workspace is loaded for use.

creationTimestamp

private javax.xml.datatype.XMLGregorianCalendar creationTimestamp

The time stamp when this workspace was created. This is currently unused and is present mostly for sanity checks to be done at a later date.

dataSetList

private java.util.ArrayList<DataSet> dataSetList

The list of data sets that have been configured for use in this work space. This list is either loaded from an XML file or populated by data set entries created by the user.

serverList

private ServerList serverList

The list of Server classes that have been configured for use in this work space. This list is either loaded from an XML file or populated by Server entries created by the user.

jobList

private JobList jobList

The list of Job classes that have been configured for use in this work space. This list is either loaded from an XML file or populated by Job entries created by the user.

classifierList

private ClassifierList classifierList

The list of data base classifiers that are used to classify and group ESTs obtained from different data bases. This information is persited and loaded from an XML work space file.

listeners

private transient java.util.ArrayList<WorkspaceListener> listeners

The list of listeners that are currently registered to receive notifications on changes that have occured to various entries in the workspace. Listeners are managed via the addWorkspaceListener() and removeWorkspaceListener() methods. The listeners are notified via the fireWorkspaceChange() method.

seqCounter

private long seqCounter

Sequence counter that is maintained on a per-work space basis to generate unique/valid IDs for each new entry that is added to this workspace.

Constructor Detail

Workspace

private Workspace()

The default constructor. The constructor has been made private to ensure that this class is never directly instanted and there is only one unique instance of this class in each PEACE GUI process. The users of this class must use the get() method.

Method Detail

get

public static Workspace get()

Method to get a reference to the process-wide, unique instance of the PEACE workspace. The PEACE workspace object is a singleton ( there is only one object). Making changes in one affects all of the views of the workspace.

Returns:

The process-wide, unique instance of PEACE workspace, if one is available. If a workspace has not been created, then this method returns null.

See Also:

useWorkspace(String), createDefault(String)

createDefault

public static Workspace createDefault(java.lang.String directory)
                               throws java.lang.Exception

Method to create default work space met data in a given directory. This method assumes that the file named "PEACEWorkspace.xml" in the given directory can be overwritten if it exists. The created workspace does not have any data sets, servers, or jobs in it. If errors occur during the creation the existing workspace remains untouched. On successful creation, the global workspace is changed to the newly created workspace (this tantamounts to calling useWorkspace method)

Parameters:

directory - The new workspace directory where an empty work space needs to be created.

Returns:

The reference to the newly created, global workspace. This will be the same object returned by the Workspace.get() method once this call is successful.

Throws:

java.lang.Exception - This method generates exception if the workspace file could not be created.

useWorkspace

public static Workspace useWorkspace(java.lang.String directory)
                              throws java.lang.Exception

Method to load workspace data from a given directory. This method assumes that the given directory contains the "PEACEWorkspace.xml" file, loads the workspace file, and parses the data into convenient class hierarchy encapsulated by this class.

Parameters:

directory - The new workspace directory from where the necessary data is to be loaded.

Throws:

java.lang.Exception - This method generates exception if the workspace file does not exist or the data in the workspace file is corrupted/inconsistent with expectations

getWorkspaceFile

public static java.lang.String getWorkspaceFile(java.lang.String directory)

Method to provide consistent name for the PEACE workspace file name so that the file names are consistently used throughout.

Parameters:

directory - The workspace directory from where the necessary data is to be loaded.

validate

protected static void validate(org.w3c.dom.Document workspace)
                        throws java.lang.Exception

This is a helper method that can be used to validate a Workspace DOM tree against the PEACE schema. If the DOM document is valid, this method silently returns. Otherwise it throws an exception to signal errors.

Parameters:

workspace - The DOM document to be verified.

Throws:

java.lang.Exception - This method generates exceptions if the PEACE.xsd file could not be loaded or if the DOM document is invalid.

marshall

public org.w3c.dom.Document marshall()
                              throws java.lang.Exception

Obtain a new DOM document representing the data associated with the current work space configuration information. This method creates a new DOM document and populates it with all the configuration information associated with the workspace. The DOM tree can then be used for various transformations.

Returns:

A newly created DOM Document that contains all the configuration data associated with this workspace.

Throws:

java.lang.Exception - This method throws a suitable exception if errors occur during the DOM creation process.

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. This method provides better control on the XML formatting to generate a more readable XML output when compared to the DOM tree.

Parameters:

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

saveWorkspaceViaDOM

public void saveWorkspaceViaDOM()
                         throws java.lang.Exception

This method can be used to save the work space configuration to disk. This method (unlike the saveWorkspace() method) uses a DOM tree to save the data. The DOM tree containing the work space configuration information is obtained from via the marhsal method.

Throws:

java.lang.Exception - This method throws a suitable exception if errors occur during the file saving process.

saveWorkspace

public void saveWorkspace()
                   throws java.lang.Exception

Save the current work space configuration information. This method saves the current work space configuration in a suitable XML format. The default work space directory and file name are used. This method does not create a DOM tree. Instead XML data is directly generated. This basically ensures that the XML is formatted to look a bit more organized and readable than otherwise.

Throws:

java.lang.Exception - This method throws a suitable exception if errors occur during the file saving process.

loadCoreWorkspaceData

private static Workspace loadCoreWorkspaceData(org.w3c.dom.Document workspaceData,
                                               java.lang.String directory)
                                        throws java.lang.Exception

Helper method to simply load the top-level Directory for the Workspace and the creation time stamp for this workspace from a DOM document.

Parameters:

workspaceData - The DOM document from where the workspace information is to be retrieved and stored in this class.

Returns:

This method creates a new workspace object, populates it with the core information and returns it.

Throws:

java.lang.Exception - This method generates exceptions if errors occur when reading the workspace data.

getDirectory

public java.lang.String getDirectory()

Obtain the directory where all the files pertaining to this workspace are stored by default.

Returns:

The default directory where files for this workspace are stored.

getServerList

public ServerList getServerList()

Obtain the ServerList that encapsulates the list of Servers that have been configured in this workspace.

Returns:

The server list object that encapsulates all the servers configured on this workspace.

getJobList

public JobList getJobList()

Obtain the JobList that encapsulates the list of Jobs that have been configured in this workspace.

Returns:

The list job object that encapsulates all the job run via this workspace.

getDataSets

public java.util.ArrayList<DataSet> getDataSets()

Obtain the list of data sets associated with this workspace.

Returns:

The list of data set entries associated with this work space. The object returned by this method is never null. However, the data set can be empty.

getMSTData

public MSTData getMSTData(java.lang.String jobID)

Obtain the MSTData entry for a given job ID.

Parameters:

jobID - The ID of the job for which the MST data is to be searched and retrieved.

Returns:

The MSTData corresponding to the given job ID. If the entry was not found this method returns null.

getClusterData

public MSTClusterData getClusterData(java.lang.String jobID)

Obtain the MSTClusterData entry for a given job ID.

Parameters:

jobID - The ID of the job for which the cluster entry is to be searched and retrieved.

Returns:

The MSTClusterData corresponding to the given job ID. If the entry was not found this method returns null.

toString

public java.lang.String toString()

Provides a string of the form Workspace (../path) to display some workspace related information to the user.

Overrides:

toString in class java.lang.Object

Returns:

A simple string representation of this workspace.

reserveID

public java.lang.String reserveID()

Reserves the next sequence number for use in a data set. This method is used only when a data set object is added to this workspace. Entries loaded from a persisted workspace file will have sequence numbers already filled in.

Returns:

A new, unique (within the work space) ID for use with a new entry.

addWorkspaceListener

public void addWorkspaceListener(WorkspaceListener listener)

Add a workspace listener to receive change notification events from this workspace.

Parameters:

listener - The listener to be added to the list of listeners to receive notifications.

removeWorkspaceListener

public void removeWorkspaceListener(WorkspaceListener listener)

Remove a workspace listener from the listeners to receive notification events from this workspace.

Parameters:

listener - The listener to removed from the list of listeners to receive notifications.

fireWorkspaceChanged

public void fireWorkspaceChanged(WorkspaceEvent event)

Utility method to notify all the listeners about a change to the Workspace. This method is used by various classes to report changes occuring to the workspace. This method is invoked by various classes constituting the workspace.

Parameters:

event - The event to be dispatched to various listeners informing them about the change to the workspace.

addDataSet

public void addDataSet(DataSet dataSet)

Method to add a new data set to the workspace. This method adds the new data set to the workspace and notifies all the listeners with a suitable event.

Parameters:

dataSet - The data set to be added to the workspace.

removeDataSet

public void removeDataSet(DataSet dataSet)

Method to add a new data set to the workspace. This method adds the new data set to the workspace and notifies all the listeners with a suitable event.

Parameters:

dataSet - The data set to be added to the workspace.

getClassifierList

public ClassifierList getClassifierList()

Obtain the classifier list set for this work space.

Returns:

The classifier list set for this work space.