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 8.
• The only 3rd-party dependency is SLF4J.

Installation

The project artifacts are available in Maven Central Repository.

Maven:

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

Gradle:

implementation("org.zeroturnaround:zt-exec:1.13.0")

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();

---

• Returning the exit code
• Output is pumped to NullOutputStream

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

---

• Return output as UTF8 String

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

---

• Pumping the output to a logger

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

---

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

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

---

• Pumping the output to the logger of the caller class

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

---

• 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();

---

• 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();

---

• 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
}

---

• Pumping output to another OutputStream

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

---

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

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

---

• 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();

---

• Destroy the running process when VM exits
• Output pumped to NullOutputStream

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

---

• Run process with a specific environment variable
• Output pumped to NullOutputStream

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

---

• Run process with a specific environment
• Output pumped to NullOutputStream

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

---

• 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());
}

---

• 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();
}

---

• 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);

---

• 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();

Building

The project is built with Gradle via the bundled wrapper, so no local Gradle installation is required:

./gradlew build

The main classes target Java 8 bytecode; the JPMS module-info for org.zeroturnaround.exec is shipped as a Java 9 multi-release entry. The build resolves the required Java toolchain automatically (it is downloaded on demand if not already installed), so the build itself runs on any modern JDK.

Releasing

Versions follow Semantic Versioning (MAJOR.MINOR.PATCH, e.g. 1.13.0) and release tags use the vMAJOR.MINOR.PATCH form (e.g. v1.13.0). Tags created before this convention use the older zt-exec-<version> form.

Releases are cut with the Release GitHub Actions workflow (Actions → Release → Run workflow). It takes the release version (e.g. 1.13.0) and then builds, publishes to Maven Central, tags the commit, creates the GitHub release, and sets the next development version.

The workflow also promotes the ## [Unreleased] section of CHANGELOG.md into a dated ## [x.y.z] section and updates the comparison links, so the only changelog task is to make sure the changes being released are listed under ## [Unreleased] beforehand. (The release fails if that section is empty.)