Package org.sosy_lab.common

Class ProcessExecutor<E extends Exception>

java.lang.Object

org.sosy_lab.common.ProcessExecutor<E>

Type Parameters:

E - The type of the exceptions the handle* methods may throw.

public class ProcessExecutor<E extends Exception>
extends Object

This class can be used to execute a separate process and read its output in a convenient way. It is only useful for processes which handle only one task and exit afterwards.

This class is not thread-safe, it assumes that never two of its methods are executed simultaneously.

When an instance of this class is created, the corresponding process is started immediately. Then some text may be written to stdin of the process with the println(String) method. Afterwards join() has to be called, which reads the output from the process and calls the handle* methods. This method blocks, i.e. when it returns the process has terminated. Now the get* methods may be used to get the output of the process.

Field Summary

Fields

Modifier and Type	Field	Description
protected final LogManager	logger

Constructor Summary

Constructors

Constructor	Description
ProcessExecutor(LogManager logger, Class<E> exceptionClass, @Nullable File executionDirectory, String... cmd)	See ProcessExecutor(LogManager, Class, File, String...).
ProcessExecutor(LogManager logger, Class<E> exceptionClass, String... cmd)	See ProcessExecutor(LogManager, Class, String...).
ProcessExecutor(LogManager logger, Class<E> exceptionClass, Map<String,String> environmentOverride, @Nullable File executionDirectory, String... cmd)	Create an instance and immediately execute the supplied command with the supplied environment variables.
ProcessExecutor(LogManager logger, Class<E> exceptionClass, Map<String,String> environmentOverride, String... cmd)	See ProcessExecutor(LogManager, Class, Map, String...).

Method Summary

Modifier and Type	Method	Description
List<String>	getErrorOutput()	Returns the complete output to stderr of the process.
List<String>	getOutput()	Returns the complete output of the process.
protected void	handleErrorOutput(String line)	Handle one line of stderr output from the process.
protected void	handleExitCode(int code)	Handle the exit code of the process.
protected void	handleOutput(String line)	Handle one line of output from the process.
boolean	isFinished()	Checks whether the process has finished already.
int	join()	Wait for the process to terminate and read all of it's output.
int	join(long timelimit)	Wait for the process to terminate.
void	print(String s)	Write a String to the process.
void	println(String s)	Write a String to the process.
void	sendEOF()	Sends the EOF (end of file) signal to stdin of the process.

Methods inherited from class java.lang.Object

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

Field Details

logger

protected final LogManager logger

Constructor Details

ProcessExecutor

public ProcessExecutor(LogManager logger,
 Class<E> exceptionClass,
 String... cmd)
                throws IOException

See ProcessExecutor(LogManager, Class, String...).

Throws:

IOException

ProcessExecutor

public ProcessExecutor(LogManager logger,
 Class<E> exceptionClass,
 @Nullable File executionDirectory,
 String... cmd)
                throws IOException

See ProcessExecutor(LogManager, Class, File, String...).

Throws:

IOException

ProcessExecutor

public ProcessExecutor(LogManager logger,
 Class<E> exceptionClass,
 Map<String,String> environmentOverride,
 String... cmd)
                throws IOException

See ProcessExecutor(LogManager, Class, Map, String...).

Throws:

IOException

ProcessExecutor

public ProcessExecutor(LogManager logger,
 Class<E> exceptionClass,
 Map<String,String> environmentOverride,
 @Nullable File executionDirectory,
 String... cmd)
                throws IOException

Create an instance and immediately execute the supplied command with the supplied environment variables.

The map with the environment parameters will override the values from the default environment. Values in the map may be null, which means that this variable is removed from the environment. Null is not allowed as a key in the map.

Whenever a line is read on stdout or stderr of the process, the handleOutput(String) or the handleErrorOutput(String) are called respectively.

It is strongly advised to call join() sometimes, as otherwise there may be resources not being cleaned up properly. Also exceptions thrown by the handling methods would get swallowed.

Parameters:

logger - A LogManager for debug output.

exceptionClass - The type of exception that the handler methods may throw.

environmentOverride - Map with environment variables to set.

executionDirectory - The directory for the command to be executed in.

cmd - The command with arguments to execute.

Throws:

IOException - If the process cannot be executed.

See Also:

• Runtime.exec(String[])

Method Details

println

public void println(String s)
             throws IOException

Write a String to the process. May only be called before join() was called, as afterwards the process is not running anymore.

Throws:

IOException

print

public void print(String s)
           throws IOException

Write a String to the process. May only be called before join() was called, as afterwards the process is not running anymore.

Throws:

IOException

sendEOF

public void sendEOF()
             throws IOException

Sends the EOF (end of file) signal to stdin of the process.

Throws:

IOException

join

public int join(long timelimit)
         throws IOException,
E,
TimeoutException,
InterruptedException

Wait for the process to terminate.

Parameters:

timelimit - Maximum time to wait for process (in milliseconds)

Returns:

The exit code of the process.

Throws:

IOException - passed from the handle* methods.

E - passed from the handle* methods.

TimeoutException - If timeout is hit.

InterruptedException - If the current thread is interrupted.

join

public int join()
         throws IOException,
E,
InterruptedException

Wait for the process to terminate and read all of it's output. Whenever a line is read on stdout or stderr of the process, the handleOutput(String) or the handleErrorOutput(String) are called respectively.

Returns:

The exit code of the process.

Throws:

IOException - passed from the handle* methods.

E - passed from the handle* methods.

InterruptedException - If the current thread is interrupted.

handleOutput

protected void handleOutput(String line)
                     throws E

Handle one line of output from the process. This method may be overwritten by clients. The default implementation logs the line on level ALL and adds it to a list which may later be retrieved with getOutput(). It never throws an exception (but client implementations may do so).

This method will be called in a new thread.

Throws:

E - Overwriting methods may throw this exception which will be propagated.

handleErrorOutput

protected void handleErrorOutput(String line)
                          throws E

Handle one line of stderr output from the process. This method may be overwritten by clients. The default implementation logs the line on level WARNING and adds it to a list which may later be retrieved with getErrorOutput(). It never throws an exception (but client implementations may do so).

This method will be called in a new thread.

Throws:

E - Overwriting methods may throw this exception which will be propagated.

handleExitCode

protected void handleExitCode(int code)
                       throws E

Handle the exit code of the process. This method may be overwritten by clients. The default implementation logs the code on level WARNING, if it is non-zero.

This method will be called in a new thread.

Throws:

E - Overwriting methods may throw this exception which will be propagated.

isFinished

public boolean isFinished()

Checks whether the process has finished already. This is true exactly if join() has been called.

getOutput

public List<String> getOutput()

Returns the complete output of the process. May only be called after join() has been called.

getErrorOutput

public List<String> getErrorOutput()

Returns the complete output to stderr of the process. May only be called after join() has been called.