ExecRunner (BioJava-1.5-beta API)
Keywords: org.biojava.utils.ExecRunner class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.biojava.utils
Class ExecRunner

    java.lang.Object
      org.biojava.utils.ExecRunner

    public class ExecRunner

extends Object

Makes running external executables easier, optionally under a watched thread. In addition, probably the most useful feature of ExecRunner is using it to run a command-line program and obtain its stdout and stderr results in two strings. This is done with exec(String) - see that method for an example. With acknowledgements to Michael C. Daconta, author of "Java Pitfalls, Time Saving Solutions, and Workarounds to Improve Programs." and his article in JavaWorld "When Runtime.exec() Won't".

Version:
  CVS $Id: ExecRunner.java,v 1.3 2006/05/24 10:40:45 draeger Exp $
Author:
  Scott McCrory., Francois Pepin, Andreas Dräger

Constructor Summary
`ExecRunner()` Basic ExecRunner constructor.
`ExecRunner(String command)` ExecRunner constructor which also conveniently runs exec(String).
`ExecRunner(String command, String[] arguments)` ExecRunner constructor which also conveniently runs exec(String).

Method Summary
`Object` | `clone()` We override the `clone` method here to prevent cloning of our class.
`int` | `exec(String command)` The exec(String) method runs a process inside of a watched thread.
`int` | `exec(String command, OutputStream stdoutStream, OutputStream stderrStream)` Convenience method for calling exec with OutputStreams.
`int` | `exec(String command, PrintWriter stdoutWriter, PrintWriter stderrWriter)` The `exec(String, PrintWriter, PrintWriter)` method runs a process inside of a watched thread.
`int` | `exec(String command, String[] arguments)` Sometimes special cases may occur that the arguments of an external program are Strings containing white spaces.
`int` | `exec(String command, String[] arguments, OutputStream stdoutStream, OutputStream stderrStream)` Convenience method for calling exec with OutputStreams.
`int` | `exec(String command, String[] arguments, PrintWriter stdoutWriter, PrintWriter stderrWriter)` The `exec(String, PrintWriter, PrintWriter)` method runs a process inside of a watched thread.
`String` | `getErrString()` Returns the error string if exec(String) was invoked.
`boolean` | `getMaxRunTimeExceeded()` Returns whether the maximum runtime was exceeded or not.
`int` | `getMaxRunTimeSecs()` Returns the maximum run time in seconds for this object.
`String` | `getOutString()` Returns the output string if exec(String) was invoked.
`static void` | `main(String[] args)` This is for unit testing of the class.
`void` | `setMaxRunTimeSecs(int max)` Sets the maximum run time in seconds.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ExecRunner

    public ExecRunner()

  Basic ExecRunner constructor.

### ExecRunner

    public ExecRunner(String command)
               throws ExceptionInInitializerError

  ExecRunner constructor which also conveniently runs exec(String).

  Parameters:
    `command` - The program or command to run
  Throws:
    `ExceptionInInitializerError` - thrown if a problem occurs

### ExecRunner

    public ExecRunner(String command,
                      String[] arguments)
               throws ExceptionInInitializerError

  ExecRunner constructor which also conveniently runs exec(String).

  Parameters:
    `command` - The program or command to run
    `arguments` - An array of Strings in which every single String is exactly one of the program's arguments. So these arguments are allowed to contain white spaces and are marked as Strings by the system.
  Throws:
    `ExceptionInInitializerError` - thrown if a problem occurs
  Since:
    1.5

Method Detail

### clone

    public final Object clone()
                       throws CloneNotSupportedException

  We override the `clone` method here to prevent cloning of our class.

  Overrides:
    `clone` in class `Object`
  Returns:
    Nothing ever really returned since we throw a CloneNotSupportedException
  Throws:
    `CloneNotSupportedException` - To indicate cloning is not allowed

### exec

    public int exec(String command)
             throws IOException,
                    InterruptedException

  The exec(String) method runs a process inside of a watched thread. It returns the client's exit code and feeds its STDOUT and STDERR to ExecRunner's out and err strings, where you then use getOutString() and getErrString() to obtain these values. If the command String contains arguments which are Strings containing white spaces, the method

      exec(program, arguments)

  should be used instead, where `arguments` is a `String[]` array containing the arguments of the program. Example:

       // Execute the program and grab the results
       String out = "";
       String err = "";
       try {

           ExecRunner er = new ExecRunner();
           er.setMaxRunTimeSecs(maxRunTime);
           er.exec(program);
           if (!er.getMaxRunTimeExceeded()) {
               out = er.getOutString();
               err = er.getErrString();
           }
           else {
               log.error("Maximum run time exceeded!");
               continue;
           }

       }
       catch (Exception e) {
           log.error("Error executing " + program + ": " + e.getMessage());
           continue;
       }

  Parameters:
    `command` - The program or command to run
  Returns:
    The command's return code
  Throws:
    `IOException` - thrown if a problem occurs
    `InterruptedException` - thrown if a problem occurs

### exec

    public int exec(String command,
                    String[] arguments)
             throws IOException,
                    InterruptedException

  Sometimes special cases may occur that the arguments of an external program are Strings containing white spaces. Another example are external processes needing the String arguments to be characterized in a special way. In this cases it is sensefull to write every single argument in an String array. The system itselfe will mark these arguments as Strings so that these special encoding can be omitted.

  Parameters:
    `command` - The external program to be executed.
    `arguments` - An array of Strings. Every entry of this array is an argument of the external program to be executed.
  Returns:
    The command's return code
  Throws:
    `IOException` - thrown if a problem occurs
    `InterruptedException` - thrown if a problem occurs
  Since:
    1.5

### exec

    public int exec(String command,
                    OutputStream stdoutStream,
                    OutputStream stderrStream)
             throws IOException,
                    InterruptedException

  Convenience method for calling exec with OutputStreams.

  Parameters:
    `command` - The program or command to run
    `stdoutStream` - java.io.OutputStream
    `stderrStream` - java.io.OutputStream
  Returns:
    The command's return code
  Throws:
    `IOException` - thrown if a problem occurs
    `InterruptedException` - thrown if a problem occurs

### exec

    public int exec(String command,
                    String[] arguments,
                    OutputStream stdoutStream,
                    OutputStream stderrStream)
             throws IOException,
                    InterruptedException

  Convenience method for calling exec with OutputStreams.

  Parameters:
    `command` - The program or command to run
    `arguments` - An array of Strings containing the program's arguments.
    `stdoutStream` - java.io.OutputStream
    `stderrStream` - java.io.OutputStream
  Returns:
    The command's return code
  Throws:
    `IOException` - thrown if a problem occurs
    `InterruptedException` - thrown if a problem occurs
  Since:
    1.5

### exec

    public int exec(String command,
                    PrintWriter stdoutWriter,
                    PrintWriter stderrWriter)
             throws IOException,
                    InterruptedException

  The `exec(String, PrintWriter, PrintWriter)` method runs a process inside of a watched thread. It returns the client's exit code and feeds its STDOUT and STDERR to the passed-in streams.

  Parameters:
    `command` - The program or command to run
    `stdoutWriter` - java.io.PrintWriter
    `stderrWriter` - java.io.PrintWriter
  Returns:
    The command's return code
  Throws:
    `IOException` - thrown if a problem occurs
    `InterruptedException` - thrown if a problem occurs

### exec

    public int exec(String command,
                    String[] arguments,
                    PrintWriter stdoutWriter,
                    PrintWriter stderrWriter)
             throws IOException,
                    InterruptedException

  The `exec(String, PrintWriter, PrintWriter)` method runs a process inside of a watched thread. It returns the client's exit code and feeds its STDOUT and STDERR to the passed-in streams. The arguments for the external program or command are passed as an array of Strings. This has the advantage that the arguments are allowed to contain white spaces and are marked to be Strings by the System itselfe, which is sometimes important. Every single argument has to be exactly one dimension of the arguments array.

  Parameters:
    `command` - The program or command to run
    `arguments` - An array of Strings containing the program's arguments/options.
    `stdoutWriter` - java.io.PrintWriter
    `stderrWriter` - java.io.PrintWriter
  Returns:
    The command's return code
  Throws:
    `IOException` - thrown if a problem occurs
    `InterruptedException` - thrown if a problem occurs
  Since:
    1.5

### getErrString

    public String getErrString()

  Returns the error string if exec(String) was invoked.

  Returns:
    The error string if exec(String) was invoked.

### getMaxRunTimeExceeded

    public boolean getMaxRunTimeExceeded()

  Returns whether the maximum runtime was exceeded or not.

  Returns:
    boolean indicating whether the maximum runtime was exceeded or not.

### getMaxRunTimeSecs

    public int getMaxRunTimeSecs()

  Returns the maximum run time in seconds for this object.

  Returns:
    the maximum run time in seconds for this object.

### getOutString

    public String getOutString()

  Returns the output string if exec(String) was invoked.

  Returns:
    The output string if exec(String) was invoked.

### main

    public static void main(String[] args)
                     throws IOException

  This is for unit testing of the class.

  Parameters:
    `args` - an array of command-line arguments
  Throws:
    `IOException` - thrown if a problem occurs

### setMaxRunTimeSecs

    public void setMaxRunTimeSecs(int max)

  Sets the maximum run time in seconds. If you do not want to limit the executable's run time, simply pass in a 0 (which is also the default).

  Parameters:
    `max` - Maximim number of seconds to let program run

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD