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
CyJobExecutionServiceis responsible for creating (and implementing) the
CyJobobject, which is the object that maintains the state of the remote job and gets serialized and deserialized in sessions. Implementations of
CyJobExecutionServiceshould store enough information in their
CyJobobject to restore the state of the job across sessions. Note that
CyJobExecutionServicesare, in fact, services. That is, there is expected to be one service running for all jobs and all uses. As such, implementations of
CyJobExecutionServiceshould not store any state.
- An implementation of
CyJobDataService, which provides the marshalling and unmarshalling of the data. The
CyJobDataServiceis responsible for creating and implementing the
CyJobDataobject, which contains all of the data to be sent to the remote service. Typically, a
CyJobExecutionServicewill use a particular
CyJobDataServicethat works with it's remote service. A given
CyJobDataServicemight be used by multiple
CyJobExecutionServices. As noted above, implementations of
CyJobDataServiceare also services and should not store any state. If the implementation provides methods to serialize
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
- An app, that will choose the appropriate
CyJobExecutionService, implement a
org.cytoscape.jobs.CyJobHandlerto listen for status changes in jobs and when the job is complete load the data and merge it into Cytoscape (if appropriate).
- An app will use OSGi to find the
CyJobExecutionServiceit is interested in utilizing.
- The app will create an empty
- The app should register a method that implements
org.cytoscape.jobs.CyJobHandlerto be notified of changes in the job status
- The app should then retreive the
CyJobExecutionServiceand add any data necessary to submit the job.
- The app will then call
CyJobis the empty job that was created in step #2
String, if not null will override the basePath in the
CyJobfor establishing a connection to the remote servic e
Mapcontains any configuration information required to execute the job. This might include authentication credentials or algorithm options.
- and the
CyJobDatais the data to be serialized and sent as input for the remote job
- If the
CyJobStatusindicates that the submission was successful, the job should be added to the
CyJobExecutionService.checkJobStatus(org.cytoscape.jobs.CyJob)and report the results to the App's
- 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
Taskis executed by the
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
Taskso 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:
- The job might return an error of some sort (). The
CyJobManagernotes the error and the user is informed in GUI.
- The user might save the session. This requires the state information in the
CyJobto be saved in the session by calling the
- When the session is restored, the
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.
ClassDescriptionThis can be used as a base class for custom implementations of
CyJobrepresents all of the state information necessary to marshal and unmarshal data, submit jobs, query job status, and fetch results.CyJobData presents a general interface to sending data to and receiving data from a job.The main interface for the marshalling and unmarshalling of data to be exchanged with remote services.The
CyJobExecutionServiceis a stateless service that can be used to provide remote job services, including the execution, cancellation, status checking, and retrieval of results.
CyJobManageris responsible for managing all currently running
CyJobs, including polling for changes in the
Statusof the job and notifying the
CyJobMonitorprovided by the App of the change in status.Apps are expected to implement this interface to receive notifications about job completions.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.This enum contains the primary status returned from the remote execution.This utility class provides methods to save and restore SUIDs that are sent to remote execution environments across sessions.