common.io
Class ProcessExecutor

java.lang.Object
  extended by common.io.ProcessExecutor

public class ProcessExecutor
extends java.lang.Object

A class that encapsulates running a process and processing its streams.

This class uses the CommonControls thread pool to monitor the process's input and output streams, and allows the caller to easily parse the outputs by using a visitor pattern.

Since:
CC 1.4.3
Version:
$Id$
Author:
Marcelo Vanzin

Nested Class Summary
static class ProcessExecutor.BufferingVisitor
          A visitor that just buffers the output of the process and makes it available for retrieval.
static interface ProcessExecutor.LineVisitor
          Interface defining a visitor that will be called with lines of text read from the process output.
static interface ProcessExecutor.Visitor
          Interface defining a visitor that will be called with data read from the child process's output.
 
Constructor Summary
ProcessExecutor(java.lang.String... cmd)
          Creates a new executor for the given process with the given arguments.
 
Method Summary
 ProcessExecutor addCurrentEnv()
          Adds the current process's environment to the child.
 ProcessExecutor addEnv(java.lang.String name, java.lang.String value)
          Adds a specific environment to use with the child process.
 ProcessExecutor addVisitor(ProcessExecutor.LineVisitor v)
          Adds a visitor instance to use with the child process.
 ProcessExecutor addVisitor(ProcessExecutor.Visitor v)
          Adds a visitor to monitor the child process's output.
 int exitValue()
          Returns the exit value of the child process.
 ProcessExecutor setDirectory(java.lang.String cwd)
          Sets the working directory for the child process.
 java.lang.Process start()
          Executes the child commmand, returning a process on success.
 int waitFor()
          Waits for execution of the child process to finish.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ProcessExecutor

public ProcessExecutor(java.lang.String... cmd)
Creates a new executor for the given process with the given arguments.

Parameters:
cmd - The command to execute. The first argument is the executable, which should be an absolute path, or be in the user's PATH. The remaining are arguments to the executable.
Method Detail

setDirectory

public ProcessExecutor setDirectory(java.lang.String cwd)
Sets the working directory for the child process.

Parameters:
dir - Path to the working directory.
Returns:
this.

addCurrentEnv

public ProcessExecutor addCurrentEnv()
Adds the current process's environment to the child.

This allows the current environment to be inherited by the child process, while still allowing customization using addEnv(String, String).

Returns:
this

addEnv

public ProcessExecutor addEnv(java.lang.String name,
                              java.lang.String value)
Adds a specific environment to use with the child process.

Calling this method makes the child ignore the current process's environment. See addCurrentEnv() for how to inherit the current environment.

Parameters:
name - Name of variable to set.
value - Value of variable.
Returns:
this.

addVisitor

public ProcessExecutor addVisitor(ProcessExecutor.Visitor v)
Adds a visitor to monitor the child process's output.

Parameters:
v - A visitor.
Returns:
this.

addVisitor

public ProcessExecutor addVisitor(ProcessExecutor.LineVisitor v)
Adds a visitor instance to use with the child process.

Parameters:
v - The visitor to use.
Returns:
this.

start

public java.lang.Process start()
                        throws java.io.IOException
Executes the child commmand, returning a process on success.

Returns:
A process on success, null otherwise.
Throws:
java.io.IOException

waitFor

public int waitFor()
            throws java.lang.InterruptedException
Waits for execution of the child process to finish.

Returns:
Exit code of the process.
Throws:
java.lang.InterruptedException

exitValue

public int exitValue()
Returns the exit value of the child process.

Returns:
Child's exit code.