bcds.tools
Class Exec

java.lang.Object
  bcds.tools.Exec

public class Exec
extends java.lang.Object

Executes an external program, waits for its completion and redirects its standard output and standard error to user-provided destinations. All IO exceptions are wrapped into unchecked exceptions of type AnyException.

The redirection is performed to a java.io.Writer instance, thus, if the caller knows that the output volume is small, he/she can can be use objects of type java.io.StringWriter.

Example:

  {
     Exec prg = new Exec("myprog", "-this", "-that", "myfile.txt");

     prg.run();

     // Another variant, with stdout and stderr combined.
     StringWriter out = new StringWriter();
     Exec prg_redir = new Exec(out, out,
                              "myprog", "-v", "myfile.txt");
     prg_redir.run();
     ...

     // A variant that does not require explicitinstantiation.
     String [] output = {"", ""};
     Exec.run(output, "myprog", "-v", "myfile.txt");

     System.out.printf("Out: %s\nErr: %s", output[0], output[1]);
     ...
  }
 

Author:

Juan Segovia S.

Constructor Summary

Exec()

Exec(java.lang.String... cmd)
Creates an instance with stderr and stdout bound to System.out and System.err, respectively.

Exec(java.io.Writer stdout, java.io.Writer stderr, java.lang.String... cmd)
Creates an instance with redirected output.

Method Summary

java.lang.String[]	getCmd() Returns the command that is instance executes.
java.io.Writer	getStdErr() Returns the Writer to which stderr is redirected.
java.io.Writer	getStdOut() Returns the Writer to which stdout is redirected.
int	run() Runs the command and returns its exit code.
static int	run(java.lang.String[] output, java.lang.String... cmd) Executes the command given in cmd and returns the command's stdout in output[0] and the command's stderr in output[1].

Methods inherited from class java.lang.Object

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

Constructor Detail

Exec

public Exec()

Exec

public Exec(java.lang.String... cmd)

Creates an instance with stderr and stdout bound to System.out and System.err, respectively. The parameter cmd must be non-null and non-empty.

Exec

public Exec(java.io.Writer stdout,
            java.io.Writer stderr,
            java.lang.String... cmd)

Creates an instance with redirected output. The parameter cmd must be a non-null non-empty string. If stdout is null, cmd' stdout is redirected to System.out. If stderr is null, cmd' stderr is redirected to System.err.

Method Detail

getStdOut

public java.io.Writer getStdOut()

Returns the Writer to which stdout is redirected.

getStdErr

public java.io.Writer getStdErr()

Returns the Writer to which stderr is redirected.

getCmd

public java.lang.String[] getCmd()

Returns the command that is instance executes.

run

public int run()

Runs the command and returns its exit code. Runtime.getRuntime().exec(cmd) is used to execute the command. Customarily, an exit code of 0 means "success" but only the caller may know the meaning of the program's exit code.

The command's stderr is always read after stdout's output has been sent to its destination. Thus, if stderr and stdout are combined, their contents will always be in the given sequence.

Throws:

AnyException - wrapping InterruptedIOException thrown by Process.waitFor().

AnyException - wrapping any IOException.

run

public static int run(java.lang.String[] output,
                      java.lang.String... cmd)

Executes the command given in cmd and returns the command's stdout in output[0] and the command's stderr in output[1].

The parameter output must be an initialized array of at least two elements.

The exceptions thrown are the same as run().

Example of use:

 {
    String [] output = {"", ""};
    int exit_code = Exec.run(output, "myprog", "-p1", "-p2");

    System.out.printf("Out:\n%s\nErr:\n%s\n", output[0], output[1]);
    ...
 }