com.biomatters.geneious.publicapi.utilities

Class Execution

java.lang.Object

com.biomatters.geneious.publicapi.utilities.Execution

public class Execution
extends Object

Executes an external program. The program isn't started immediately when an instance of this class is constructed, but only when the execute() method is called.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Execution.OutputListener Reports output received from an external process.

Constructor Summary

Constructors

Constructor and Description
Execution(String[] commandArray, Cancelable cancelable, Execution.OutputListener outputListener, InputStream inputStream, boolean tryToEmulateTerminal) Constructs an Execution object that represents an execution of an external program.
Execution(String[] commandArray, Cancelable cancelable, Execution.OutputListener outputListener, String input, boolean tryToEmulateTerminal) Constructs an Execution object that represents an execution of an external program.

Method Summary

Methods

Modifier and Type	Method and Description
int	execute() Starts execution of the external program represented by this object.
int	execute(Map<String,String> environment) Starts execution of the external program represented by this object.
boolean	isEmulatingTerminal() Return true if this process is being executed by emulating a terminal.
protected boolean	isSafeToKillOutReadThread() Tells Execution whether it is safe to end the thread which reads stdout from the process.
void	setWorkingDirectory(String workingDirectory) Set the working directory of the external process.
protected void	setWritingFinished() Called when stdout has finished being read.
boolean	wasKilledByGeneious() Returns true if the process was terminated by Geneious due to the Cancelable passed to the constructor requesting that the process execution be canceled.

Methods inherited from class java.lang.Object

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

Constructor Detail

Execution

public Execution(String[] commandArray,
         Cancelable cancelable,
         Execution.OutputListener outputListener,
         String input,
         boolean tryToEmulateTerminal)

Constructs an Execution object that represents an execution of an external program. When this method returns, the execution is not yet started - to start it, call execute().

Parameters:

commandArray - The components of the command line, the first of which is the path of the program to execute.

cancelable - A callback which can be queried by the Execution object to determine whether termination of the external program has been requested. Must not be null, but may be ProgressListener.EMPTY.

outputListener - A callback that is notified when the external program produces output. If progress is to be reported (in this case cancelable was probably derived from a ProgressListener) then it is recommended that outputListener internally stores a copy of that ProgressListener and calls it.

input - The input to provide on the external program's stdin. May be "" or a String variable with value null in which case no input will be provided to stdin. A null constant would be ambiguous and cause a compile time error

tryToEmulateTerminal - true if we should try to emulate a terminal (to create an unbuffered stdout/stderr on Windows). Even if this parameter is true, the Execution implementation may choose to ignore it on unsupported operating systems. See isEmulatingTerminal().

Execution

public Execution(String[] commandArray,
         Cancelable cancelable,
         Execution.OutputListener outputListener,
         InputStream inputStream,
         boolean tryToEmulateTerminal)

Constructs an Execution object that represents an execution of an external program. When this method returns, the execution is not yet started - to start it, call execute().

Parameters:

commandArray - The components of the command line, the first of which is the path of the program to execute.

cancelable - A callback which can be queried by the Execution object to determine whether termination of the external program has been requested. Must not be null, but may be ProgressListener.EMPTY.

outputListener - A callback that is notifed when the external program produces output. If progress is to be reported (in this case cancelable was probably derived from a ProgressListener) then it is recommended that outputListener internally stores a copy of that ProgressListener and calls it.

inputStream - The input to provide on the external program's stdin. May be an InputStream variable with null value in which case no input will be provided to stdin. A null constant would be ambiguous and cause a compile time error

tryToEmulateTerminal - true if we should try to emulate a terminal (to create an unbuffered stdout/stderr on Windows). Even if this parameter is true, the Execution implementation may choose to ignore it on unsupported operating systems. See isEmulatingTerminal().

Since:

Geneious API 4.30 (Geneious 5.3.0)

Method Detail

setWritingFinished

protected void setWritingFinished()

Called when stdout has finished being read. This method can be overridden to allow clean up when the process has finished producing output (eg. closing streams). Overriding methods should call super.setWritingFinished

isSafeToKillOutReadThread

protected boolean isSafeToKillOutReadThread()

Tells Execution whether it is safe to end the thread which reads stdout from the process. The thread will be kept alive as long as this returns false. By default this method returns true when the process has finished but it can be overridden to keep the thread alive longer. This method should not perform any clean up because it is called throughout execution. Override setWritingFinished() instead for this purpose. Overriding methods should also check super.isSafeToKillOutReadThread.

Returns:

true if it safe to end the thread which is reading stdout, false to keep it alive.

execute

public int execute()
            throws InterruptedException,
                   IOException

Starts execution of the external program represented by this object. Calling this method is the same as calling execute(java.util.Map) with an empty map.

Returns:

the exit code returned from the external process.

Throws:

InterruptedException - If such an exception is thrown when trying to wait for the external program to finish (see Process.waitFor() or waiting for the threads that poll the process' stdout/stderr to die (see Thread.join()).

IOException - If such an exception occurs while trying to execute the external program

execute

public int execute(Map<String,String> environment)
            throws InterruptedException,
                   IOException

Starts execution of the external program represented by this object. The environment map is used to add or replace values in the environment variables inherited from the execution's parent process.

Parameters:

environment - A map containing the environment variables the process is to be run with. See ProcessBuilder.environment()

Returns:

the exit code returned from the external process.

Throws:

InterruptedException - If such an exception is thrown when trying to wait for the external program to finish (see Process.waitFor() or waiting for the threads that poll the process' stdout/stderr to die (see Thread.join()).

IOException - If such an exception occurs while trying to execute the external program

setWorkingDirectory

public void setWorkingDirectory(String workingDirectory)

Set the working directory of the external process. This must be invoked before calling execute().

Parameters:

workingDirectory - the working directory to set.

wasKilledByGeneious

public boolean wasKilledByGeneious()

Returns true if the process was terminated by Geneious due to the Cancelable passed to the constructor requesting that the process execution be canceled.

Returns:

true if the process was terminated by Geneious due to the Cancelable passed to the constructor requesting that the process execution be canceled.

isEmulatingTerminal

public boolean isEmulatingTerminal()

Return true if this process is being executed by emulating a terminal. This is to work around a problem where the system interface to external processes buffers the output from the external process, and it only forwards the output in batches once the buffer has been filled. This means that we don't receive regular updates to standardout from the process and hence are unable to give useful progress reports. By proxying the process through a custom terminal emulater we can receive regular updates. However, this seems to cause problems with some executables so is enabled on a case by case basis.

Returns:

true if this process is being executed by emulating a terminal.