Module JavaProc

Package com.simtechdata.process

Class ProcBuilder

java.lang.Object

com.simtechdata.process.ProcBuilder

public class ProcBuilder
extends Object

A builder to construct a new process. The process gets configured by the withXXX-methods and spawned by the run() method

Constructor Summary

Constructors

Constructor	Description
ProcBuilder(String command, String... args)	Creates a new ProcBuilder

Method Summary

Modifier and Type	Method	Description
ProcBuilder	clearEnvironment()	Clears the environment before setting new variables.
static String	filter(String input, String cmd, String... args)	Static helper to filter a string through a process
String	getCommandLine()
String	getProcString()	Deprecated. Use getCommandLine instead.
ProcBuilder	ignoreExitStatus()	Ignore the error status returned from this command
ProcResult	run()	Spawn the actual execution.
static String	run(String cmd, String... args)	Static helper to run a process
ProcBuilder	withArg(String arg)	Adds another argument
ProcBuilder	withArgs(String... args)	Add multiple args
ProcBuilder	withErrorConsumer(StreamConsumer errorConsumer)	Process the error output with given consumer object
ProcBuilder	withErrorStream(OutputStream stderr)	Redirecting the error output.
ProcBuilder	withExitStatuses(int[] exitstatuses)	Deprecated. Please use the variants with a set or vargs parameters
ProcBuilder	withExpectedExitStatuses(int... expectedExitStatuses)	Define the valid exit status codes for the command Convenience method taking varargs.
ProcBuilder	withExpectedExitStatuses(Set<Integer> expectedExitStatuses)	Define the valid exit status codes for the command
ProcBuilder	withInput(byte[] input)	Supply the input as byte[]
ProcBuilder	withInput(String input)	Supply the input as string
ProcBuilder	withInputStream(InputStream stdin)	Take the input for the program from a given InputStream
ProcBuilder	withNoTimeout()	Disable timeout for the operation.
ProcBuilder	withOutputConsumer(StreamConsumer outputConsumer)	Process the standard output with the given consumer object
ProcBuilder	withOutputStream(OutputStream stdout)	Redirecting the standard output.
ProcBuilder	withTimeoutMillis(long timeoutMillis)	Specify a timeout for the operation.
ProcBuilder	withVar(String var, String value)	Add a variable to the process's environment
ProcBuilder	withVars(Map<String,String> vars)	Add multiple variables to the process's environment
ProcBuilder	withWorkingDirectory(File directory)	Override the working directory

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcBuilder

public ProcBuilder(String command,
                   String... args)

Creates a new ProcBuilder

Parameters:

command - The command to run

args - The command line arguments

Method Detail

withArg

public ProcBuilder withArg(String arg)

Adds another argument

Parameters:

arg - to add

Returns:

this, for chaining

withOutputStream

public ProcBuilder withOutputStream(OutputStream stdout)

Redirecting the standard output. If it is not redirected the output gets captured in memory and is available on the @see ProcResult

Parameters:

stdout - stream to redirect the output to. \

Returns:

this, for chaining

withErrorStream

public ProcBuilder withErrorStream(OutputStream stderr)

Redirecting the error output. If it is not redirected the output gets captured in memory and is available on the @see ProcResult

Parameters:

stderr - stream to redirect the output to. \

Returns:

this, for chaining

withTimeoutMillis

public ProcBuilder withTimeoutMillis(long timeoutMillis)

Specify a timeout for the operation. If not specified the default is 5 seconds.

Parameters:

timeoutMillis - time that the process gets to run

Returns:

this, for chaining

withNoTimeout

public ProcBuilder withNoTimeout()

Disable timeout for the operation.

Returns:

this, for chaining

withInputStream

public ProcBuilder withInputStream(InputStream stdin)

Take the input for the program from a given InputStream

Parameters:

stdin - stream to read the input from

Returns:

this, for chaining

withInput

public ProcBuilder withInput(String input)

Supply the input as string

Parameters:

input - the actual input

Returns:

this, for chaining

withInput

public ProcBuilder withInput(byte[] input)

Supply the input as byte[]

Parameters:

input - the actual input

Returns:

this, for chaining

withWorkingDirectory

public ProcBuilder withWorkingDirectory(File directory)

Override the working directory

Parameters:

directory - the working directory for the process

Returns:

this, for chaining

withArgs

public ProcBuilder withArgs(String... args)

Add multiple args

Parameters:

args - the arguments add

Returns:

this, for chaining

withExitStatuses

public ProcBuilder withExitStatuses(int[] exitstatuses)

Deprecated.

Please use the variants with a set or vargs parameters

Define the valid exit status codes for the command

Parameters:

exitstatuses - array containing the exit codes that are valid

Returns:

the ProcBuilder object; permits chaining.

withExpectedExitStatuses

public ProcBuilder withExpectedExitStatuses(Set<Integer> expectedExitStatuses)

Define the valid exit status codes for the command

Parameters:

expectedExitStatuses - array containing the exit codes that are valid

Returns:

the ProcBuilder object; permits chaining.

withExpectedExitStatuses

public ProcBuilder withExpectedExitStatuses(int... expectedExitStatuses)

Define the valid exit status codes for the command Convenience method taking varargs.

Parameters:

expectedExitStatuses - varargs parameter containing the exit codes that are valid

Returns:

the ProcBuilder object; permits chaining.

ignoreExitStatus

public ProcBuilder ignoreExitStatus()

Ignore the error status returned from this command

Returns:

the ProcBuilder object; permits chaining.

run

public ProcResult run()
               throws StartupException,
                      TimeoutException,
                      ExternalProcessFailureException

Spawn the actual execution. This will block until the process terminates.

Returns:

the result of the successful execution

Throws:

StartupException - if the process can't be started

TimeoutException - if the timeout kicked in

ExternalProcessFailureException - if the external process returned a non-null exit value

run

public static String run(String cmd,
                         String... args)

Static helper to run a process

Parameters:

cmd - the command

args - the arguments

Returns:

the standard output

Throws:

StartupException - if the process can't be started

TimeoutException - if the timeout kicked in

ExternalProcessFailureException - if the external process returned a non-null exit value

filter

public static String filter(String input,
                            String cmd,
                            String... args)

Static helper to filter a string through a process

Parameters:

input - the input to be fed into the process

cmd - the command

args - the arguments

Returns:

the standard output

Throws:

StartupException - if the process can't be started

TimeoutException - if the timeout kicked in

ExternalProcessFailureException - if the external process returned a non-null exit value

clearEnvironment

public ProcBuilder clearEnvironment()

Clears the environment before setting new variables.

withVar

public ProcBuilder withVar(String var,
                           String value)

Add a variable to the process's environment

Parameters:

var - variable name

value - the value to be passed in

Returns:

this, for chaining

withVars

public ProcBuilder withVars(Map<String,String> vars)

Add multiple variables to the process's environment

Parameters:

vars - Map of variables to their respective values

Returns:

this, for chaining

withOutputConsumer

public ProcBuilder withOutputConsumer(StreamConsumer outputConsumer)

Process the standard output with the given consumer object

Parameters:

outputConsumer - an object that defines how to process the standard output stream

Returns:

this, for chaining

withErrorConsumer

public ProcBuilder withErrorConsumer(StreamConsumer errorConsumer)

Process the error output with given consumer object

Parameters:

errorConsumer - an object that defines how to process the error output stream

Returns:

this, for chaining

getProcString

@Deprecated
public String getProcString()

Deprecated.

Use getCommandLine instead.

Returns:

a string representation of the process invocation.

This approximates the representation of this invocation in a shell. Note that the escaping of arguments is incomplete, it works only for whitespace. Fancy control characters are not replaced.

Also, this returns a representation of the current state of the builder. If more arguments are added the process this representation will not represent the process that gets launched.

getCommandLine

public String getCommandLine()

Returns:

a string representation of the process invocation.

This approximates the representation of this invocation in a shell. Note that the escaping of arguments is incomplete, it works only for whitespace. Fancy control characters are not replaced.

Also, this returns a representation of the current state of the builder. If more arguments are added the process this representation will not represent the process that gets launched.