The GridPlugin Class (Primary Method)

The implementation must package the given program-execution command and dispatch it to the other execution framework, marshal supporting files, monitor the resulting job, and either return the executed program’s termination code or report execution failure (usually by throwing a Java exception).

The following example shows the primary method that must be implemented: 

public int submitJobAndWait(
   String[]       cmd,
   String[]       inFiles,
   String[]       outFiles,
   File           localWorkingDir,
   Log            log
) throws RtGridException;

The following arguments are used by the class:

  • String[] cmd. The command that is executed by the other framework. It is represented as an array of the individual tokens of the command line. The first entry is usually the name of the program or shell script that will be executed.

  • String[] inFiles. When not null, this entry is a list of the fully qualified names of all of the component’s input files. The method must arrange for these files to be copied from the current working directory into whatever directory the other framework uses for executing its commands.

  • String[] outFiles. When not null, this entry is a list of the fully qualified names of all of the component’s output files. The method must arrange for these files to be copied from whatever directory the other framework uses for executing its commands to the current working directory.

    Note: Sometimes all machines are mounted on a shared file system (depending on your local network structure). When this structure is used, it is not necessary for files to be moved. The system selected by the Grid tool will be able to run the program “in place” over the working directory provided by Isight. If this scenario matches your implementation, your version of this method may ignore the inFiles and outFiles arguments.

  • File localWorkingDir. The runtime scratch directory created by Isight to hold the input and output files. The method needs this information when it copies these files in either direction.

  • Log log. The Isight runtime Job Log object. This method may log errors, warning, or other information before, during, and after the dispatched command executes.

The following methods are used with the GridPlugin class when creating a Grid plug-in:

  • public int waitForJob() throws RtGridException;

    This method waits for a previously dispatched program-execution command to finish executing and either returns the executed program’s termination code or reports execution failure (usually by throwing a Java exception). The core method submitJobAndWait()should end by calling this method and returning its result.

  • public void terminateJob() throws RtGridException;

    This method directs a previously dispatched program-execution command to stop executing if it is still executing and removes it from the other framework. This method is typically called when the execution time limit of the command’s Isight component expires to terminate a command that the other framework has launched as an independent process (usually on a completely different machine).

  • public void pauseJob() throws RtGridException;

    This method directs a previously dispatched program-execution command to stop executing, preserving the execution state so that it can be restarted. The command can be called when the associated component is paused, such as in response to clicking the Isight Runtime Gateway Pause button.

    Important: This method is not currently used by Isight because it is not always possible to stop an execution in a “restartable” manner. Implementation of this method may do nothing or may throw a “method not implemented” Java exception. Nevertheless, you should implement this method as described.

  • public void resumeJob() throws RtGridException;

    This method directs a previously dispatched but stopped program-execution command to resume executing. It may be called when the associated component is resumed, such as in response to the user clicking the Isight Runtime Gateway Resume button after clicking the Pause button.

    Important: This method is not currently used by Isight because it is not always possible to stop an execution in a “restartable” manner. Implementation of this method may do nothing or may throw a “method not implemented” Java exception. Nevertheless, you should implement this method as described.

  • public int getJobStatus() throws RtGridException;

    This method queries the other framework and returns an integer code denoting the status of the dispatched program-execution command. The returned value must be “0” if the command ran to completion without error. Otherwise, the returned value is nonzero. There are no other requirements placed on the returned value. You should capture the return code of the executed command and return that value.

  • public String getJobStatusAsString() throws RtGridException;

    This method queries the other framework and returns a string denoting the status of the dispatched program-execution command. The returned string is intended for display, so it must not be “null.” Otherwise, there are no requirements placed on the string.

  • public String getJobIDAsString() throws RtGridException;

    It is assumed that the other framework will create and return an identification string to keep track of the program-execution command when it is dispatched. This string is used by other framework tools, and the plug-in will record and retain this string during execution. This method returns that identifier. If the other framework does not create an identifier, the plug-in must create one.

  • public GridOptionsPanel getOptionsPanel () throws RtGridException;

    This method constructs and returns a GridOptionsPanel instance. This instance may be cached for reuse. Since it is a component of the GUI, it must also at least be an object of class java.awt.Component; otherwise, it cannot be displayed. The OS Command component editor requires that it be of class javax.swing.JComponent. The most convenient approach is to extend the class javax.swing.JPanel. Its constructor can then configure the panel with any necessary property-editing widgets.