eu.planets_project.services.utils
Class ProcessRunner

java.lang.Object
  eu.planets_project.services.utils.ProcessRunner

All Implemented Interfaces:

Runnable

public class ProcessRunner
extends Object
implements Runnable

Native command executor. Based on ProcessBuilder.

• Incorporates timeout for spawned processes.
• Handle automatic collection of bytes from the output and error streams, to ensure that they dont block.
• Handles automatic feeding of input to the process.
• Blocking while executing
• Implements Runnable, to be wrapped in a Thread.

Use the Assessor methods to configure the Enviroment, input, collecting behavoiur, timeout and startingDir. Use the getters to get the output and error streams as strings, along with the return code and if the process timed out.

This code is not yet entirely thread safe. Be sure to only call a given processRunner from one thread, and do not reuse it.

Constructor Summary

ProcessRunner()
Create a new ProcessRunner.

ProcessRunner(List<String> commands)
Create a new ProcessRunner with the given command.

ProcessRunner(String command)
Create a new ProcessRunner with just this command, with no arguments.

Method Summary

InputStream	getProcessError() The OutputStream will either be the error-OutputStream directly from the execution of the native commands or a cache with the error-output of the execution of the native commands.
String	getProcessErrorAsString() Return what was printed on the error channel of a _finished_ process, as a string, including newlines.
InputStream	getProcessOutput() The OutputStream will either be the OutputStream directly from the execution of the native commands or a cache with the output of the execution of the native commands.
String	getProcessOutputAsString() Return what was printed on the output channel of a _finished_ process, as a string, including newlines.
int	getReturnCode() Get the return code of the process.
boolean	isTimedOut() Tells whether the process has timedout.
void	run() Run the method, feeding it input, and killing it if the timeout is exceeded.
void	setCollection(boolean collect) Decide if the outputstreams should be collected.
void	setCommand(List<String> commands) Set the command for this ProcessRunner.
void	setEnviroment(Map<String,String> enviroment) Sets the enviroment that the process should run in.
void	setErrorCollectionByteSize(int maxError) How many bytes should we collect from the ErrorStream.
void	setInputStream(InputStream processInput) Set the inputstream, from which the process should read.
void	setOutputCollectionByteSize(int maxOutput) How many bytes should we collect from the OutputStream.
void	setStartingDir(File startingDir) The directory to be used as starting dir.
void	setTimeout(long timeout) Set the timeout.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessRunner

public ProcessRunner()

Create a new ProcessRunner. Cannot run, until you specify something with the assessor methods.

ProcessRunner

public ProcessRunner(String command)

Create a new ProcessRunner with just this command, with no arguments. Spaces are not allowed in the string

Parameters:

command - the command to run

ProcessRunner

public ProcessRunner(List<String> commands)

Create a new ProcessRunner with the given command. Each element in the list should be a command or argument. If the element should not be parsed enclose it in \"'s.

Parameters:

commands - the command to run

Method Detail

setEnviroment

public void setEnviroment(Map<String,String> enviroment)

Sets the enviroment that the process should run in. For the the equivalent to the command

 export FLIM=flam
 echo $FLIM
 

put "FLIM","flam" in the enviroment.

Parameters:

enviroment - The Map containing the mapping in the enviroment.

setInputStream

public void setInputStream(InputStream processInput)

Set the inputstream, from which the process should read. To be used if you need to give commands to the process, after it has begun.

Parameters:

processInput - to read from.

setStartingDir

public void setStartingDir(File startingDir)

The directory to be used as starting dir. If not set, uses the dir of the current process.

Parameters:

startingDir - the starting dir.

setCommand

public void setCommand(List<String> commands)

Set the command for this ProcessRunner.

Parameters:

commands - the new command.

setTimeout

public void setTimeout(long timeout)

Set the timeout. Default to Long.MAX_VALUE in millisecs

Parameters:

timeout - the new timeout in millisecs

setCollection

public void setCollection(boolean collect)

Decide if the outputstreams should be collected. Default true, ie, collect the output.

Parameters:

collect - should we collect the output

setErrorCollectionByteSize

public void setErrorCollectionByteSize(int maxError)

How many bytes should we collect from the ErrorStream. Will block when limit is reached. Default 31000. If set to negative values, will collect until out of memory.

Parameters:

maxError - number of bytes to max collect.

setOutputCollectionByteSize

public void setOutputCollectionByteSize(int maxOutput)

How many bytes should we collect from the OutputStream. Will block when limit is reached. Default 31000; If set to negative values, will collect until out of memory.

Parameters:

maxOutput - number of bytes to max collect.

getProcessOutput

public InputStream getProcessOutput()

The OutputStream will either be the OutputStream directly from the execution of the native commands or a cache with the output of the execution of the native commands.

Returns:

the output of the native commands.

getProcessError

public InputStream getProcessError()

The OutputStream will either be the error-OutputStream directly from the execution of the native commands or a cache with the error-output of the execution of the native commands.

Returns:

the error-output of the native commands.

getReturnCode

public int getReturnCode()

Get the return code of the process. If the process timed out and was killed, the return code will be -1. But this is not exclusive to this scenario, other programs can also use this return code.

Returns:

the return code

isTimedOut

public boolean isTimedOut()

Tells whether the process has timedout. Only valid after the process has been run, of course.

Returns:

has the process timed out.

getProcessOutputAsString

public String getProcessOutputAsString()

Return what was printed on the output channel of a _finished_ process, as a string, including newlines.

Returns:

the output as a string

getProcessErrorAsString

public String getProcessErrorAsString()

Return what was printed on the error channel of a _finished_ process, as a string, including newlines.

Returns:

the error as a string

run

public void run()

Run the method, feeding it input, and killing it if the timeout is exceeded. Blocking.

Specified by:

run in interface Runnable

See Also:

Runnable.run()