Package org.kiwiproject.beta.base.process

Class ProcessHelpers

java.lang.Object

org.kiwiproject.beta.base.process.ProcessHelpers

@Beta
public final class ProcessHelpers
extends Object

Utilities to execute a command using a ProcessHelper.

These static methods could be considered for addition to kiwi's ProcessHelper. They would be instance methods inside ProcessHelper. Static versions of the methods could also be added to kiwi's Processes class (which contains only static utilities), and then the instance methods in ProcessHelper would delegate, thereby providing two ways to use this. Using ProcessHelper is more friendly to testing since it can easily be mocked.

Method Summary

Modifier and Type	Method	Description
static ProcessResult	execute(org.kiwiproject.base.process.ProcessHelper processHelper, List<String> command)	Execute command with timeout of 5 seconds.
static ProcessResult	execute(org.kiwiproject.base.process.ProcessHelper processHelper, List<String> command, long timeout, TimeUnit timeoutUnit)	Execute command with the given timeout.
static ProcessResult	execute(org.kiwiproject.base.process.ProcessHelper processHelper, List<String> command, Duration timeout)	Execute command with the given timeout.
static Process	launchCommand(@Nullable File workingDirectory, String command)	Convenience method that splits the given command on spaces before passing it to Processes.launch(List).
static Process	launchCommand(String command)	Convenience method that splits the given command on spaces before passing it to Processes.launch(List).
static Process	launchPipeline(@Nullable File workingDirectory, List<List<String>> commands)	Executes a pipeline of the given commands.
static Process	launchPipeline(List<List<String>> commands)	Executes a pipeline of the given commands.
static Process	launchPipelineCommand(@Nullable File workingDirectory, String pipeline)	Convenience method that splits a pipeline using "|" and then splits each individual command on spaces.
static Process	launchPipelineCommand(String pipeline)	Convenience method that splits a pipeline using "|" and then splits each individual command on spaces.

Methods inherited from class java.lang.Object

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

Method Details

execute

public static ProcessResult execute(org.kiwiproject.base.process.ProcessHelper processHelper,
 List<String> command)

Execute command with timeout of 5 seconds.

Implementation Note:

See the implementation note in execute(ProcessHelper, List, long, TimeUnit).

execute

public static ProcessResult execute(org.kiwiproject.base.process.ProcessHelper processHelper,
 List<String> command,
 Duration timeout)

Execute command with the given timeout.

See Also:

• execute(ProcessHelper, List, long, TimeUnit)

execute

public static ProcessResult execute(org.kiwiproject.base.process.ProcessHelper processHelper,
 List<String> command,
 long timeout,
 TimeUnit timeoutUnit)

Execute command with the given timeout.

Implementation Note:

This uses CompletableFuture to ensure we time out even if the stdout or stderr blocks, which according to the Process docs, can at least theoretically happen. For example, if someone gives the command ls -laR / to list all files in the filesystem, it will probably take quite a long time.

launchCommand

public static Process launchCommand(String command)

Convenience method that splits the given command on spaces before passing it to Processes.launch(List).

Warning: If a command argument contains spaces and needs to be quoted, you cannot use this method. Instead, use Processes.launch(List) or Processes.launch(String...). The reason is that this method just splits on all spaces, so arguments with spaces would be broken up, and the quotes would become part of the two separate arguments. In other words, this method is not a command parser.

Parameters:

command - the command to execute

Returns:

the new Process

Throws:

UncheckedIOException - if anything goes wrong, for example if the working directory does not exist

launchCommand

public static Process launchCommand(@Nullable File workingDirectory,
 String command)

Convenience method that splits the given command on spaces before passing it to Processes.launch(List). The command uses the given working directory.

Warning: See the warning in launchCommand(String).

Parameters:

workingDirectory - the working directory for the command

command - the command to execute

Returns:

the new Process

Throws:

UncheckedIOException - if anything goes wrong, for example if the working directory does not exist

launchPipelineCommand

public static Process launchPipelineCommand(String pipeline)

Convenience method that splits a pipeline using "|" and then splits each individual command on spaces.

Warning: The same caveats on command splitting on spaces apply to this method, as described in launchCommand(String). For similar reasons, nested pipelines won't work either.

Parameters:

pipeline - the pipeline command

Returns:

the last Process in the pipeline

Throws:

UncheckedIOException - if anything goes wrong, for example if the working directory does not exist

See Also:

• ProcessBuilder.startPipeline(java.util.List<java.lang.ProcessBuilder>)

launchPipelineCommand

public static Process launchPipelineCommand(@Nullable File workingDirectory,
 String pipeline)

Convenience method that splits a pipeline using "|" and then splits each individual command on spaces. Each command in the pipeline uses the given working directory.

Warning: The same caveats on command splitting on spaces apply to this method, as described in launchCommand(String). For similar reasons, nested pipelines won't work either.

Parameters:

workingDirectory - the working directory for each command in the pipeline

pipeline - the pipeline command

Returns:

the last Process in the pipeline

Throws:

UncheckedIOException - if anything goes wrong executing the command

See Also:

• ProcessBuilder.startPipeline(java.util.List<java.lang.ProcessBuilder>)

launchPipeline

public static Process launchPipeline(List<List<String>> commands)

Executes a pipeline of the given commands.

Parameters:

commands - the commands in the pipeline

Returns:

the last Process in the pipeline

Throws:

UncheckedIOException - if anything goes wrong executing the command

See Also:

• ProcessBuilder.startPipeline(java.util.List<java.lang.ProcessBuilder>)

launchPipeline

public static Process launchPipeline(@Nullable File workingDirectory,
 List<List<String>> commands)

Executes a pipeline of the given commands.

Each command in the pipeline uses the given working directory.

Parameters:

workingDirectory - the working directory for each command in the pipeline

commands - the commands in the pipeline

Returns:

the last Process in the pipeline

Throws:

UncheckedIOException - if anything goes wrong, for example if the working directory does not exist

See Also:

• ProcessBuilder.startPipeline(java.util.List<java.lang.ProcessBuilder>)