com.continuent.tungsten.common.exec
Class ProcessExecutor

java.lang.Object
  com.continuent.tungsten.common.exec.ProcessExecutor

All Implemented Interfaces:

java.lang.Runnable

public class ProcessExecutor
extends java.lang.Object
implements java.lang.Runnable

Wrapper class to encapsulate all aspects of executing native operating system commands which are typically characterized . The wrapper handles up-front collection of inputs such as setting the working directory, environment, and stdin. It also manages the collection output from stdout and stderr.

Here is an example of typical usage:

 ProcessExecutor pe = new ProcessExecutor();
 pe.setCommands(new String[] {"echo", "hi!"});
 pe.setTimeout(1000);
 pe.setEnv("myenvvar", "myvalue");
 pe.run();
 

After the run() method completes it is safe for clients to examine output values. The class is implemented as runnable to permit callers to run it easily in another thread.

Version:

1.0

Author:

Robert Hodges

Field Summary

protected java.lang.String[]	commands
protected java.util.HashMap<java.lang.String,java.lang.String>	env
protected java.lang.Throwable	error
protected int	exitValue
protected java.lang.Process	process
protected boolean	redirectStdErr
protected java.lang.String	stderr
protected boolean	stdErrAppend
protected java.io.File	stdErrFile
protected org.apache.log4j.Logger	stdErrLogger
protected java.io.InputStream	stdin
protected java.lang.String	stdout
protected boolean	stdOutAppend
protected java.io.File	stdOutFile
protected org.apache.log4j.Logger	stdOutLogger
protected boolean	succeeded
protected static int	THREAD_WAIT_MILLIS Maximum milliseconds to wait for output threads to complete after process completion.
protected boolean	timedout
protected int	timeout
protected java.io.File	workDirectory

Constructor Summary

ProcessExecutor()
Creates a new instance.

ProcessExecutor(boolean redirectStdErr)
Creates a new instance.

Method Summary

java.lang.String[]	getCommands() Returns the program and command line argumetns.
java.util.HashMap<java.lang.String,java.lang.String>	getEnv() Returns the table of environmental variables.
java.lang.Throwable	getError() Returns the exception, if any, generated while executing the command.
int	getExitValue() Returns the exit value of the command or -1 if the command failed to execute.
java.lang.Process	getProcess() Returns the process value.
java.lang.String	getStderr() Returns a String containing stderr output.
java.util.List<java.lang.String>	getStderrByLine() Returns stderr in the form of a String array where each string contains one line of output.
java.io.InputStream	getStdin() Returns the inputstream fed to the process.
java.lang.String	getStdout() Returns a String containing stdout.
java.util.List<java.lang.String>	getStdoutByLine() Returns the stdout in the form of a String array where each string contains one line of output.
int	getTimeout() Returns the process timeout in milliseconds.
java.io.File	getWorkDirectory() Returns the process working directory.
protected int	handleProcessIO(java.lang.Process process) Manage process input and output.
boolean	isStdErrAppend() Returns true if stderr should append to existing file.
boolean	isStdOutAppend() Returns true if stdout should append to existing file.
boolean	isSuccessful() Returns true if we think the process succeeded based on the return code and lack of exceptions or timeout during execution.
boolean	isTimedout() Returns true if this processed exceeded its timeout and was killed.
void	run() Execute the command.
void	setCommands(java.lang.String[] commands) Sets the program and command line arguments.
void	setEnv(java.util.HashMap<java.lang.String,java.lang.String> env) Sets environmental variables to be used by this command.
void	setEnv(java.lang.String name, java.lang.String value) Sets an environmental variable.
void	setStdErr(java.io.File stdErrFile) Send stderr to a file
void	setStdErr(org.apache.log4j.Logger stdErrLogger) Send stderr to a logger.
void	setStdErrAppend(boolean appendStderr) If true, append stderr to existing file.
void	setStdin(java.io.InputStream stdin) Sets the input stream fed to the process.
void	setStdOut(java.io.File stdOutFile) Send stdout to a file
void	setStdOut(org.apache.log4j.Logger stdOutLogger) Send stdout to a logger.
void	setStdOutAppend(boolean appendStdout) If true, append stdout to existing file.
void	setTimeout(int timeout) Sets the process timeout in milliseconds.
void	setWorkDirectory(java.io.File workDirectory) Sets the process working direcgtory.
static java.util.List<java.lang.String>	toStringList(java.lang.String output)

Methods inherited from class java.lang.Object

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

Field Detail

THREAD_WAIT_MILLIS

protected static final int THREAD_WAIT_MILLIS

Maximum milliseconds to wait for output threads to complete after process completion.

See Also:

Constant Field Values

env

protected java.util.HashMap<java.lang.String,java.lang.String> env

stdin

protected java.io.InputStream stdin

workDirectory

protected java.io.File workDirectory

commands

protected java.lang.String[] commands

timeout

protected int timeout

stdOutAppend

protected boolean stdOutAppend

stdErrAppend

protected boolean stdErrAppend

stdOutFile

protected java.io.File stdOutFile

stdErrFile

protected java.io.File stdErrFile

stdout

protected java.lang.String stdout

stderr

protected java.lang.String stderr

stdOutLogger

protected org.apache.log4j.Logger stdOutLogger

stdErrLogger

protected org.apache.log4j.Logger stdErrLogger

error

protected java.lang.Throwable error

exitValue

protected int exitValue

timedout

protected boolean timedout

succeeded

protected boolean succeeded

process

protected java.lang.Process process

redirectStdErr

protected boolean redirectStdErr

Constructor Detail

ProcessExecutor

public ProcessExecutor()

Creates a new instance.

ProcessExecutor

public ProcessExecutor(boolean redirectStdErr)

Creates a new instance.

Method Detail

getCommands

public java.lang.String[] getCommands()

Returns the program and command line argumetns.

setCommands

public void setCommands(java.lang.String[] commands)

Sets the program and command line arguments.

setEnv

public void setEnv(java.lang.String name,
                   java.lang.String value)

Sets an environmental variable.

getEnv

public java.util.HashMap<java.lang.String,java.lang.String> getEnv()

Returns the table of environmental variables.

setEnv

public void setEnv(java.util.HashMap<java.lang.String,java.lang.String> env)

Sets environmental variables to be used by this command.

getStdin

public java.io.InputStream getStdin()

Returns the inputstream fed to the process.

setStdin

public void setStdin(java.io.InputStream stdin)

Sets the input stream fed to the process. The input stream is automatically closed at the end of the command. Null is the default value and means there is no stdin for this process.

setStdOut

public void setStdOut(java.io.File stdOutFile)

Send stdout to a file

Parameters:

stdOutFile - a file for stdout to be stored to

setStdOut

public void setStdOut(org.apache.log4j.Logger stdOutLogger)

Send stdout to a logger.

Parameters:

stdOutLogger - an initialized Logger for stdout to be appended to.

setStdErr

public void setStdErr(java.io.File stdErrFile)

Send stderr to a file

Parameters:

stdErrFile - a file for stderr to be stored to

setStdErr

public void setStdErr(org.apache.log4j.Logger stdErrLogger)

Send stderr to a logger.

Parameters:

stdErrLogger - an initialized Logger for stderr to be appended to.

isStdOutAppend

public boolean isStdOutAppend()

Returns true if stdout should append to existing file.

setStdOutAppend

public void setStdOutAppend(boolean appendStdout)

If true, append stdout to existing file. Otherwise, stdout overwrites the file if it exists.

isStdErrAppend

public boolean isStdErrAppend()

Returns true if stderr should append to existing file.

setStdErrAppend

public void setStdErrAppend(boolean appendStderr)

If true, append stderr to existing file. Otherwise, stderr overwrites the file if it exists.

getTimeout

public int getTimeout()

Returns the process timeout in milliseconds.

setTimeout

public void setTimeout(int timeout)

Sets the process timeout in milliseconds. We consider the process failed if it does not terminate within this time. A value of 0 is the default and means to wait indefinitely.

getWorkDirectory

public java.io.File getWorkDirectory()

Returns the process working directory.

setWorkDirectory

public void setWorkDirectory(java.io.File workDirectory)

Sets the process working direcgtory. Null is the default and means to run in the current directory of the Java process that launches this command.

getError

public java.lang.Throwable getError()

Returns the exception, if any, generated while executing the command.

getExitValue

public int getExitValue()

Returns the exit value of the command or -1 if the command failed to execute.

getStderr

public java.lang.String getStderr()

Returns a String containing stderr output. An empty string means there is no output.

getStderrByLine

public java.util.List<java.lang.String> getStderrByLine()

Returns stderr in the form of a String array where each string contains one line of output.

getStdout

public java.lang.String getStdout()

Returns a String containing stdout. An empty string means there is no output.

getStdoutByLine

public java.util.List<java.lang.String> getStdoutByLine()

Returns the stdout in the form of a String array where each string contains one line of output.

isTimedout

public boolean isTimedout()

Returns true if this processed exceeded its timeout and was killed.

isSuccessful

public boolean isSuccessful()

Returns true if we think the process succeeded based on the return code and lack of exceptions or timeout during execution.

run

public void run()

Execute the command. When this method returns it is safe for callers to read output values.

Specified by:

run in interface java.lang.Runnable

handleProcessIO

protected int handleProcessIO(java.lang.Process process)
                       throws java.lang.InterruptedException

Manage process input and output. This is messy so we put it in a separate routine.

Throws:

java.lang.InterruptedException

toStringList

public static java.util.List<java.lang.String> toStringList(java.lang.String output)

getProcess

public java.lang.Process getProcess()

Returns the process value.

Returns:

Returns the process.