dlife.tools.xgrid
Class XgridCommand

java.lang.Object
  dlife.tools.xgrid.XgridCommand

public class XgridCommand
extends Object

A command to be submitted to the Xgrid as a job. This class essentially presents an interface to some (but not all) of the features of the xgrid command line tool (see the Xgrid man page for more information).

Version:

Jun 7, 2007

Author:

Grant Braught, Dickinson College

Constructor Summary

XgridCommand(String cmd)
Construct a new XgridCommand that can be used to submit the specified command to an xgrid as a job.

XgridCommand(String si, String in, String so, String se, String out, String cmd)
Construct a new XgridCommand that can be used to submit the specified command to an xgrid as a job.

Method Summary

void	deleteJob(String host, String password, String grid) Delete this command's job from the xgrid controller.
String	getCommand() Get the command to be executed on the xGrid agent.
String	getInputDir() Get the path to the working directory that is to be copied to each agent for the execution of this command.
String	getJobID() Get the xgrid ID of the job that is running this command.
String	getOutputDir() Get the path of the directory to which any files created by the execution of this command should be copied.
XgridResult	getResults(String host, String password, String grid) Get the results of the job for this command.
String	getStandardError() Get the path of the file to which all output written to standard error by the execution of this command should be copied.
String	getStandardIn() Get the path to the file that is to be used for standard input for the execution of this command.
String	getStandardOut() Get the path of the file to which all output written to standard output by the execution of this command should be copied.
boolean	isFinished(String host, String password, String grid) Determine if the job for this XgridCommand finished successfully.
boolean	isRunning(String host, String password, String grid) Determine if the job for this XgridCommand is still running.
boolean	jobFailed(String host, String password, String grid) Determine if the job for this XgridCommand failed.
void	stopJob(String host, String password, String grid) Stop this command's job on the xgrid controller but do not delete it.
String	submitJob(String host, String password, String grid) Submit this command to the xgrid as a job.
String	toString() Get a String representation of this XgridCommand.

Methods inherited from class java.lang.Object

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

Constructor Detail

XgridCommand

public XgridCommand(String cmd)

Construct a new XgridCommand that can be used to submit the specified command to an xgrid as a job. The specified command should be a command line that can be executed on any node on the xgrid.

Parameters:

cmd - the command.

Throws:

IllegalArgumentException - if cmd is null.

XgridCommand

public XgridCommand(String si,
                    String in,
                    String so,
                    String se,
                    String out,
                    String cmd)

Construct a new XgridCommand that can be used to submit the specified command to an xgrid as a job. The full complement of xgrid options are available using this constructor. Any options set to null will not be included in the xgrid job that is created. See the xGrid documentation for more information regarding and examples of each of the parameters. Note: All files and directories should be specified with full path names on the local machine.

Parameters:

si - the the file to be used as standard input for the job.

in - the working directory to submit with the job. This should be a full path name on the local machine.

so - the file to which standard output from the job should be written. This should be a full path name on the local machine.

se - the file to which standard error from the job should be written. This should be a full path name on the local machine.

out - the directory in which the results (files generated by) the job. This should be a full path name on the local machine.

cmd - the command to be submitted.

Throws:

IllegalArgumentException - if cmd is null.

Method Detail

getStandardIn

public String getStandardIn()

Get the path to the file that is to be used for standard input for the execution of this command.

Returns:

the file used for standard input or null if not input file has been specified.

getInputDir

public String getInputDir()

Get the path to the working directory that is to be copied to each agent for the execution of this command.

Returns:

the working directory to copy or null if no working directory has been specified.

getStandardOut

public String getStandardOut()

Get the path of the file to which all output written to standard output by the execution of this command should be copied.

Returns:

the file that will hold standard output or null if no file has been specified.

getStandardError

public String getStandardError()

Get the path of the file to which all output written to standard error by the execution of this command should be copied.

Returns:

the file that will hold standard error or null if no file has been specified.

getOutputDir

public String getOutputDir()

Get the path of the directory to which any files created by the execution of this command should be copied.

Returns:

the directory for any output files, or null if no directory has been specified.

getCommand

public String getCommand()

Get the command to be executed on the xGrid agent.

Returns:

the command.

getJobID

public String getJobID()

Get the xgrid ID of the job that is running this command.

Returns:

the xgridID or null if the command has not yet been submitted.

submitJob

public String submitJob(String host,
                        String password,
                        String grid)

Submit this command to the xgrid as a job. This method does not wait for the job to complete before returning. This method also sets the job id for this XgridCommand to the id assigned by the xgrid controller.

Parameters:

host - the hostname of the grid controller to which to submit the commands. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Returns:

the xgrid job identifier for the submitted job.

Throws:

XgridCommunicationError - if unable to connect to the xgrid (e.g. bad host or password or the xgrid is down).

BadXgridCommandException - if the xgrid command line utility is unable to execute the command.

IllegalStateException - if this XgridCommand has already been submitted.

getResults

public XgridResult getResults(String host,
                              String password,
                              String grid)

Get the results of the job for this command. This returns and XgridResult containing the standard output from the job (if -so was not used) as well as other relevant statistics. See the XgridResult class for more information.

Parameters:

host - the hostname of the grid controller from which to retrieve the results. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Returns:

the results of the job. If the job is finished (i.e. isRunning() returns false) then the returned XgridResult will contain all of the results and all files will be retrieved from the xgrid controller (as appropriate). If the job is not finished the returned XgridResult will contain the current attributes of the job but not the results.

Throws:

IllegalStateException - if this XgridCommand has not yet been submitted or the job has been deleted.

deleteJob

public void deleteJob(String host,
                      String password,
                      String grid)

Delete this command's job from the xgrid controller. If the job is running it is stopped and then deleted.

Parameters:

host - the hostname of the grid controller from which to delete the job. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Throws:

XgridCommunicationException - if unable to delete the job.

IllegalStateException - if this XgridCommand has not yet been submitted.

stopJob

public void stopJob(String host,
                    String password,
                    String grid)

Stop this command's job on the xgrid controller but do not delete it. Stopping a job that has already finished, failed or is already stopped has no effect.

Parameters:

host - the hostname of the grid controller on which to stop the job. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Throws:

XgridCommunicationException - if unable to stop the job.

IllegalStateException - if this XgridCommand has not yet been submitted.

isFinished

public boolean isFinished(String host,
                          String password,
                          String grid)

Determine if the job for this XgridCommand finished successfully.

Parameters:

host - the hostname of the grid controller on which to check for the running job. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Returns:

true if this XgridCommand has finished successfully and false if it has either not been submitted, it is running, it has been stopped or it failed.

Throws:

IllegalStateException - if this XgridCommand has already been deleted.

isRunning

public boolean isRunning(String host,
                         String password,
                         String grid)

Determine if the job for this XgridCommand is still running. For the purposes of this method, the job is running if it is not finished, failed or canceled.

Parameters:

host - the hostname of the grid controller on which to check for the running job. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Returns:

true if this XgridCommand is running and false if it has either not been submitted or it has completed (either successfully or failed).

Throws:

IllegalStateException - if this XgridCommand has already been deleted.

jobFailed

public boolean jobFailed(String host,
                         String password,
                         String grid)

Determine if the job for this XgridCommand failed. The job is considered to have failed if it is not running, not finished and not canceled.

Parameters:

host - the hostname of the grid controller to which to check for the failed job. Can be null if the XGRID_CONTROLLER_HOSTNAME environment variable is set on the machine being used.

password - the password for the grid. Can be null if the XGRID_CONTROLLER_PASSWORD environment variable is set on the machine being used or the grid does not require a password.

grid - the name of the logical grid on which the command will be run. If this is null the command will be run on the default grid. Note: xgrid uses numeric gid's to identify the grids. This is not that id, it is the text name of the grid. This method will translate automatically to the xgrid gid value.

Returns:

true if this XgridCommand has failed and false if either it has not been submitted or has completed successfully.

Throws:

IllegalStateException - if this XgridCommand has already been deleted.

toString

public String toString()

Get a String representation of this XgridCommand. The String representation is what would be typed on the command line to submit the job to xgrid.

Overrides:

toString in class Object

Returns:

a string representation of this XgridCommand.