Awesome

ZT Process Executor

Continuous Integration

Quick Overview

The project was created to merge similar functionality of projects at ZeroTurnaround into a single codebase. It's designed to be powerful but still simple to use. By using a single class ProcessExecutor the user gets the functionality from both java.lang.ProcessBuilder and Apache Commons Exec.

Dependencies

Minimal required Java version is 6 (tested also with 8, 11 and 17).
The only 3rd-party dependency is SLF4J.

Installation

The project artifacts are available in Maven Central Repository.

To include it in your maven project then you have to specify the dependency.

...
<dependency>
    <groupId>org.zeroturnaround</groupId>
    <artifactId>zt-exec</artifactId>
    <version>1.12</version>
</dependency>
...

Motivation

There are many approaches to take when running external processes from Java. There are the JRE options such as the Runtime.exec() and ProcessBuilder. Also there is the Apache Commons Exec. Nevertheless we created yet another process library (YAPL).

Some of the reasons for this crazy endeavour

Improved handling of streams
Reading/writing to streams
Redirecting stderr to stdout
Improved handling of timeouts
Improved checking of exit codes
Improved API
One liners for quite complex usecases
One liners to get process output into a String
Access to the Process object available
Support for async processes ( Future )
Improved logging with SLF4J API
Support for multiple processes

Can zt-exec also kill processes?

No. There is zt-process-killer for that.

Examples

Output is pumped to NullOutputStream

new ProcessExecutor().command("java", "-version").execute();

<hr/>

Returning the exit code
Output is pumped to NullOutputStream

int exit = new ProcessExecutor().command("java", "-version")
                  .execute().getExitValue();

<hr/>

Return output as UTF8 String

String output = new ProcessExecutor().command("java", "-version")
                  .readOutput(true).execute()
                  .outputUTF8();

<hr/>

Pumping the output to a logger

new ProcessExecutor().command("java", "-version")
      .redirectOutput(Slf4jStream.of(LoggerFactory.getLogger(getClass().getName() + ".MyProcess")).asInfo()).execute();

<hr/>

Pumping the output to a logger (short form for previous)

new ProcessExecutor().command("java", "-version")
      .redirectOutput(Slf4jStream.of("MyProcess").asInfo()).execute();

<hr/>

Pumping the output to the logger of the caller class

new ProcessExecutor().command("java", "-version")
      .redirectOutput(Slf4jStream.ofCaller().asInfo()).execute();

<hr/>

Pumping the output to a logger
Returning output as UTF8 String

String output = new ProcessExecutor().command("java", "-version")
        .redirectOutput(Slf4jStream.of(getClass()).asInfo())
        .readOutput(true).execute().outputUTF8();

<hr/>

Pumping the stderr to a logger
Returning the output as UTF8 String

String output = new ProcessExecutor().command("java", "-version")
        .redirectError(Slf4jStream.of(getClass()).asInfo())
        .readOutput(true).execute()
        .outputUTF8();

<hr/>

Running with a timeout of 60 seconds
Output pumped to NullOutputStream

try {
  new ProcessExecutor().command("java", "-version")
        .timeout(60, TimeUnit.SECONDS).execute();
}
catch (TimeoutException e) {
  // process is automatically destroyed
}

<hr/>

Pumping output to another OutputStream

OutputStream out = ...;
new ProcessExecutor().command("java", "-version")
      .redirectOutput(out).execute();

<hr/>

Handling output line-by-line while process is running (Java 8+)

new ProcessExecutor().command("java", "-version")
    .redirectOutput(line -> ...)
    .execute();

<hr/>

Handling output line-by-line while process is running (prior to Java 8)

new ProcessExecutor().command("java", "-version")
    .redirectOutput(new LogOutputStream() {
      @Override
      protected void processLine(String line) {
        ...
      }
    })
    .execute();

<hr/>

Destroy the running process when VM exits
Output pumped to NullOutputStream

new ProcessExecutor().command("java", "-version").destroyOnExit().execute();

<hr/>

Run process with a specific environment variable
Output pumped to NullOutputStream

new ProcessExecutor().command("java", "-version")
    .environment("foo", "bar").execute();

<hr/>

Run process with a specific environment
Output pumped to NullOutputStream

Map<String, String> env = ...
new ProcessExecutor().command("java", "-version")
    .environment(env).execute();

<hr/>

Throw exception when wrong exit code
Output is pumped to NullOutputStream

try {
  new ProcessExecutor().command("java", "-version")
        .exitValues(3).execute();
}
catch (InvalidExitValueException e) {
  System.out.println("Process exited with " + e.getExitValue());
}

<hr/>

Throw exception when wrong exit code
Return output as UTF8 String

String output;
boolean success = false;
try {
  output = new ProcessExecutor().command("java", "-version")
                .readOutput(true).exitValues(3)
                .execute().outputUTF8();
  success = true;
}
catch (InvalidExitValueException e) {
  System.out.println("Process exited with " + e.getExitValue());
  output = e.getResult().outputUTF8();
}

<hr/>

Starting process in the background
Output is pumped to NullOutputStream

Future<ProcessResult> future = new ProcessExecutor()
                                    .command("java", "-version")
                                    .start().getFuture();
// do some stuff
future.get(60, TimeUnit.SECONDS);

<hr/>

Start process in the background
Return output as UTF8 String

Future<ProcessResult> future = new ProcessExecutor()
                                    .command("java", "-version")
                                    .readOutput(true)
                                    .start().getFuture();
// do some stuff
String output = future.get(60, TimeUnit.SECONDS).outputUTF8();