org.systemsbiology.gaggle.core

Interface Boss3

All Superinterfaces:

org.systemsbiology.gaggle.core.Boss, org.systemsbiology.gaggle.core.Boss2, java.rmi.Remote

public interface Boss3
extends org.systemsbiology.gaggle.core.Boss2

The Boss3 interface defines APIs to handle workflow related actions. A Boss implements the Boss3 interface should receive and parse a JSON workflow string and generate the execution plan. It should automatically start geese according to the execution plan and coordinate data transmission amongst the geese.

APIs are also defined for recording workflow from users' routine usage of various geese. This is a more natural way for user to form workflows.

Another important task of Boss is to coordinate the generation of workflow reports. A workflow report is a summary of an execution of a workflow. Basically, each goose of the workflow takes a snapshot of the data it has processed and passes it to Boss. Boss subsequently passes it to the server, which stores the information in DB for later retrieval.

Method Summary

Methods

Modifier and Type	Method and Description
void	handleWorkflowAction(WorkflowAction action) Tell the boss to handle a workflow action.
void	loadState(java.lang.String stateid) Load a saved state.
java.lang.String	pauseRecordingWorkflow(java.util.UUID rid) Pause recording a workflow
void	recordAction(java.lang.String sourceGoose, java.lang.String targetGoose, java.lang.Object data, int edgeIndex, java.util.HashMap<java.lang.String,java.lang.String> sourceParams, java.util.HashMap<java.lang.String,java.lang.String> targetParams, java.util.HashMap<java.lang.String,java.lang.String> edgeParams) Record a broadcast action.
void	resumeRecordingWorkflow(java.util.UUID rid) Resume recording a workflow
void	saveState(Goose3 proxyGoose, java.lang.String userid, java.lang.String name, java.lang.String desc, java.lang.String filePrefix) Save the current state.
java.util.UUID	startRecordingWorkflow() Tell the boss to start recording a workflow.
java.lang.String	submitWorkflow(Goose3 proxyGoose, java.lang.String jsonWorkflow) Submit a workflow to the boss.
java.lang.String	terminateRecordingWorkflow(java.util.UUID rid) Tell the boss to stop recording a workflow

Methods inherited from interface org.systemsbiology.gaggle.core.Boss2

broadcastJSON, broadcastTable, register

Methods inherited from interface org.systemsbiology.gaggle.core.Boss

broadcastCluster, broadcastMatrix, broadcastNamelist, broadcastNetwork, broadcastTuple, getGooseNames, getNameHelper, hide, register, register, renameGoose, show, terminate, unregister

Method Detail

submitWorkflow

java.lang.String submitWorkflow(Goose3 proxyGoose,
                              java.lang.String jsonWorkflow)
                                throws java.rmi.RemoteException

Submit a workflow to the boss. The boss will parse the workflow and generate the execution plan. A thread will be spawned for each workflow.

A workflow is a graph of workflow components and edges Each key is the ID of a parent component Each element has two lists of workflow components that are children of the parent component. One list for parallel components, where different types of data (specified by the edge data type) is passed from the source node to all of them at once. No user intervention is required once the user triggers the "Next" operation from the source component. The other list is for sequential components, where data is passed from the source node to each of the component one by one. User intervention is required on the source node to trigger processing of each component. This allows the user to make changes on the source node before passing data to following components.

Parameters:

jsonWorkflow - A workflow wrapped in JSON string. Here is a sample workflow json string:

{"type":"workflow","workflownodes":{"wfcid0_component_7": {"id":"wfcid0_component_7","wfnodeid":"344","name":"MeV","goosename":"Multiple Array Viewer","serviceuri":"C:\\MeV_4_8_1\\TMEV.bat","arguments":"- gaggle","subaction":"","datauri":"","componentid":"7"},"wfcid1_component_4": {"id":"wfcid1_component_4","wfnodeid":"343","name":"Cytoscape","goosename":"Cytoscape","serviceuri": "C:\\Program Files\\Cytoscape_v2.8.3\\Cytoscape.exe","arguments":"","subaction":"","datauri":"", "componentid":"4"}}, "workflowedges": {"sourceid_0":"wfcid0_component_7","targetid_0":"wfcid1_component_4", "datatype_0":"Data","datatypeid_0":"7","isparallel_0":"1"}, "workflowid":"139","name":"MevCyto","desc":"From Mev to Cytoscape","userid":"1","startNode":""}

The workflow JSON string consists of three sections. The first section includes information about the workflow such as its ID, name, and description. User can also specify a startnode of the workflow. The second section contains all the nodes in a workflow graph. This section is marked by the key "workflownodes". Finally, a section is dedicated to represent edges of the workflow graph. The section is marked with the "workflowedges" key. Note that all edges are directed in the graph.

Returns:

a JSON string that includes goose information (e.g. full execution path etc). The Boss detects the execution path of each goose and pass them back to the web page to update the workflow. This saves the user effort of manually input the execution path of each goose.

Throws:

java.rmi.RemoteException - if RMI communication fails

handleWorkflowAction

void handleWorkflowAction(WorkflowAction action)
                          throws java.rmi.RemoteException

Tell the boss to handle a workflow action. The workflowAction can be either a Request or a Response.

If it is a Request, and its option field is WorkflowReportData, it contains data from the goose for generating the workflow report. Boss pass the data to the server for storage.

If it is a Response, it contains acknowledgement data passed from the source goose to the target geese. The boss should store the acknowledgement and inform each of the target goose to perform subsequent actions of the workflow. Details can be found in WorkflowAction.

Parameters:

action - A workflow action needs to be carried out.

Throws:

java.rmi.RemoteException - if RMI communication fails

startRecordingWorkflow

java.util.UUID startRecordingWorkflow()
                                      throws java.rmi.RemoteException

Tell the boss to start recording a workflow. Each boss can only process one recording session. Other requests will be rejected. Once recording starts, all the broadcast between geese are captured and stored on the Boss. User can call terminateRecordingWorkflow(java.util.UUID) to terminate recording. Or, user can call pauseRecordingWorkflow(java.util.UUID) to pause, perform some activities, and call resumeRecordingWorkflow(java.util.UUID) to resume recording.

Returns:

a UUID if the recording is started successfully null if the request is rejected.

Throws:

java.rmi.RemoteException

terminateRecordingWorkflow

java.lang.String terminateRecordingWorkflow(java.util.UUID rid)
                                            throws java.rmi.RemoteException

Tell the boss to stop recording a workflow

Parameters:

rid - The UUID generated by startRecordingWorkflow.

Throws:

java.rmi.RemoteException - return a JSON string of the recorded workflow

pauseRecordingWorkflow

java.lang.String pauseRecordingWorkflow(java.util.UUID rid)
                                        throws java.rmi.RemoteException

Pause recording a workflow

Parameters:

rid - The UUID generated by startRecordingWorkflow.

Throws:

java.rmi.RemoteException - Returns the currently recorded workflow

resumeRecordingWorkflow

void resumeRecordingWorkflow(java.util.UUID rid)
                             throws java.rmi.RemoteException

Resume recording a workflow

Parameters:

rid - The UUID generated by startRecordingWorkflow.

Throws:

java.rmi.RemoteException

recordAction

void recordAction(java.lang.String sourceGoose,
                java.lang.String targetGoose,
                java.lang.Object data,
                int edgeIndex,
                java.util.HashMap<java.lang.String,java.lang.String> sourceParams,
                java.util.HashMap<java.lang.String,java.lang.String> targetParams,
                java.util.HashMap<java.lang.String,java.lang.String> edgeParams)
                  throws java.rmi.RemoteException

Record a broadcast action. startRecordingWorkflow should be called before calling this API. The API can be used to update source goose and target goose parameters as well as edge parameters.

Parameters:

sourceGoose - the source goose of the broadcast action

targetGoose - the target goose of the broadcast action

data - the data broadcast by the source goose to the target goose

edgeIndex - The index of the edge to be updated, -1 if it's a new edge

sourceParams - The parameters for the source goose (e.g., serviceuri, subaction, etc). The definition of parameters can be found in JSONConstants. Constants prefixed with "WORKFLOW_" are supported.

targetParams - The parameters for the target goose (e.g., serviceuri, subaction, etc)

edgeParams - Parameters for an edge between source and target geese. Supported parameters include edge data type (Namelist, Tuple, Matrix, etc) and edge type (parallel or sequential).

Throws:

java.rmi.RemoteException

saveState

void saveState(Goose3 proxyGoose,
             java.lang.String userid,
             java.lang.String name,
             java.lang.String desc,
             java.lang.String filePrefix)
               throws java.rmi.RemoteException

Save the current state. The Boss will contact all the currently opened geese. As a result, all the tabs opened in Firefox and all the sessions of currently opened geese will be saved to the server. User can reload the session from any machine as long as there is internet connection.

Parameters:

proxyGoose - The goose to which the Boss passes back history and debug information.

userid - The ID of the user who will be able to save and reload the state.

name - The name of the saved session.

desc - The description of the saved session.

filePrefix - A String that will be used as the prefix of all the session files generated by the geese. Save session is an asynchronous call. The result is a JSON string that will be passed back to proxyGoose. The resulting JSON object looks like the following:

Throws:

java.rmi.RemoteException

loadState

void loadState(java.lang.String stateid)
               throws java.rmi.RemoteException

Load a saved state. The Boss will download the state files of the target state from the server, automatically start all the involved geese, and pass the state files to each of them. The geese will re-instate all the files and reload the state.

Parameters:

stateid - The ID of the saved state.

Throws:

java.rmi.RemoteException