Package com.biomatters.geneious.publicapi.utilities

Class Execution

  • public class Execution
extends java.lang.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 Description
      static class  Execution.OutputListener
      Reports output received from an external process.

    • Constructor Summary

      Constructors 
      Constructor Description
      Execution​(java.lang.String[] commandArray, jebl.util.Cancelable cancelable, Execution.OutputListener outputListener, java.io.InputStream inputStream, boolean tryToEmulateTerminal)
      Constructs an Execution object that represents an execution of an external program.
      Execution​(java.lang.String[] commandArray, jebl.util.Cancelable cancelable, Execution.OutputListener outputListener, java.lang.String input, boolean tryToEmulateTerminal)
      Constructs an Execution object that represents an execution of an external program.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int execute()
      Starts execution of the external program represented by this object.
      int execute​(java.util.Map<java.lang.String,​java.lang.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 setStdoutAndStderrSourceFiles​(java.io.File stdoutSourceFile, java.io.File stderrSourceFile)
      Instead of reading stdout and stderr from the running process, read it from the specified files instead.
      void setWorkingDirectory​(java.lang.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​(java.lang.String[] commandArray,
                 jebl.util.Cancelable cancelable,
                 Execution.OutputListener outputListener,
                 java.lang.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​(java.lang.String[] commandArray,
                 jebl.util.Cancelable cancelable,
                 Execution.OutputListener outputListener,
                 java.io.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 java.lang.InterruptedException,
                   java.io.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:
        java.lang.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()).
        java.io.IOException - If such an exception occurs while trying to execute the external program

      • execute

        public int execute​(java.util.Map<java.lang.String,​java.lang.String> environment)
            throws java.lang.InterruptedException,
                   java.io.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:
        java.lang.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()).
        java.io.IOException - If such an exception occurs while trying to execute the external program

      • setStdoutAndStderrSourceFiles

        public void setStdoutAndStderrSourceFiles​(java.io.File stdoutSourceFile,
                                          java.io.File stderrSourceFile)
        Instead of reading stdout and stderr from the running process, read it from the specified files instead. This is useful in situations where the output of a program is written to a file instead of stdout.
        Parameters:
        stdoutSourceFile - the file to read stdout from (or null to read from the running process)
        stderrSourceFile - the file to read stderr from (or null to read from the running process)
        Since:
        API 4.1000 (Geneious 10.0.0)

      • setWorkingDirectory

        public void setWorkingDirectory​(java.lang.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.