Package org.cytoscape.jobs

This package provides a mechanism for executing remote jobs from within Cytoscape.

See: Description

Interface Summary

Interface	Description
CyJob	A CyJob represents all of the state information necessary to marshal and unmarshal data, submit jobs, query job status, and fetch results.
CyJobData	CyJobData presents a general interface to sending data to and receiving data from a job.
CyJobDataService	The main interface for the marshalling and unmarshalling of data to be exchanged with remote services.
CyJobExecutionService	The CyJobExecutionService is a stateless service that can be used to provide remote job services, including the execution, cancellation, status checking, and retrieval of results.
CyJobManager	CyJobManager is responsible for managing all currently running CyJobs, including polling for changes in the Status of the job and notifying the CyJobMonitor provided by the App of the change in status.
CyJobMonitor	Apps are expected to implement this interface to receive notifications about job completions.

Class Summary

Class	Description
AbstractCyJob	This can be used as a base class for custom implementations of CyJob
CyJobStatus	This object stores information about the status of a CyJob, including the actual job status (CyJobStatus.Status) and any message returned from the remote execution.
SUIDUtil	This utility class provides methods to save and restore SUIDs that are sent to remote execution environments across sessions.

Enum Summary

Enum	Description
CyJobStatus.Status	This enum contains the primary status returned from the remote execution.

Package org.cytoscape.jobs Description

This package provides a mechanism for executing remote jobs from within Cytoscape. The goal is to provide reusable mechanisms that may be utilized by Cytoscape apps to marshal data, submit a remote job, check on the status of the submitted job, fetch the results and unmarshal the data.

There are three main components of an implementation of a remote job:

• An implementation of CyJobExecutionService, which provides communication with the remote service. The CyJobExecutionService is responsible for creating (and implementing) the CyJob object, which is the object that maintains the state of the remote job and gets serialized and deserialized in sessions. Implementations of CyJobExecutionService should store enough information in their CyJob object to restore the state of the job across sessions. Note that CyJobExecutionServices are, in fact, services. That is, there is expected to be one service running for all jobs and all uses. As such, implementations of CyJobExecutionService should not store any state.
• An implementation of CyJobDataService, which provides the marshalling and unmarshalling of the data. The CyJobDataService is responsible for creating and implementing the CyJobData object, which contains all of the data to be sent to the remote service. Typically, a CyJobExecutionService will use a particular CyJobDataService that works with it's remote service. A given CyJobDataService might be used by multiple CyJobExecutionServices. As noted above, implementations of CyJobDataService are also services and should not store any state. If the implementation provides methods to serialize CyNetworks, CyTables or CyNetworkViews, it may need to save the SUIDs of those objects to be able to restore them after session restore (SUIDs are not preserved across sessions). To assist with this, a utility class SUIDUtil is provided.
• An app, that will choose the appropriate CyJobExecutionService, implement a org.cytoscape.jobs.CyJobHandler to listen for status changes in jobs and when the job is complete load the data and merge it into Cytoscape (if appropriate).

The general flow of execution is shown in the image below, but is also described below:

1. An app will use OSGi to find the CyJobExecutionService it is interested in utilizing.
2. The app will create an empty CyJob by calling getCyJob method.
3. The app should register a method that implements org.cytoscape.jobs.CyJobHandler to be notified of changes in the job status
4. The app should then retreive the CyJobDataService from the CyJobExecutionService and add any data necessary to submit the job.
5. The app will then call executeJob, where:
   • the CyJob is the empty job that was created in step #2
   • the String, if not null will override the basePath in the CyJob for establishing a connection to the remote servic
   e
   • the Map contains any configuration information required to execute the job. This might include authentication credentials or algorithm options.
   • and the CyJobData is the data to be serialized and sent as input for the remote job
   to actually submit the job to the remote service.
6. If the CyJobStatus indicates that the submission was successful, the job should be added to the CyJobManager (org.cytoscape.jobs.CyJobManager#addJob(org.cytoscape.jobs.CyJob, org.cytoscape.jobs.CyJobHandler, int)).
7. The CyJobManager will call CyJobExecutionService.checkJobStatus(org.cytoscape.jobs.CyJob) and report the results to the App's org.cytoscape.jobs.CyJobHandler
8. After the job finishes, the user (not the App) is informed and when the user indicates that the results should be retrieved and processed, a Cytoscape Task is executed by the TaskManager. The Task will call org.cytoscape.jobs.CyJobHandler#loadData(org.cytoscape.jobs.CyJob, org.cytoscape.work.TaskMonitor) method to actually load the data. This is done within the context of a Cytoscape Task so that the standard mechanisms in Cytoscape for reporting progress to the user and avoid threading issues are utilized.

While the above describes the normal workflow, there are a couple of things that might happen that will deviate from this workflow:

1. The job might return an error of some sort (CyJobStatus.Status). The CyJobManager notes the error and the user is informed in GUI.
2. The user might save the session. This requires the state information in the CyJob to be saved in the session by calling the CyJobExecutionService.saveJobInSession(org.cytoscape.jobs.CyJob, java.io.File) method.
3. When the session is restored, the CyJobManager will call CyJobExecutionService.restoreJobFromSession(org.cytoscape.session.CySession, java.io.File) method to restore the session, reestablish the org.cytoscape.jobs.CyJobHandler (assuming that it's registered), and resuming the polling of the job.