7.7 KiB

Raw Blame History

Executor

Shell, JVM, and remote SSH command execution on Linux, MacOS, or Windows for Java 8 (no process PID information) and Java 9+ (with PID information)

Ironically, there are a considerable number of issues when launching shell/JVM processes via Java. This library solves problems with:

Redirecting in/out/err streams correctly
Enable reading a single-character from the console input-stream
Correctly reading out/err process output streams to prevent memory and threading issues
Executing a JVM process using the same JVM as is currently running
Executing remote processes via SSH
Using and supporting kotlin co-routines for thread suspension
Getting process PID information (Java 9+ only)

This is for cross-platform use, specifically - linux 32/64, mac 32/64, and windows 32/64. Java 8+, kotlin.

This project is powerful but still simple to use. By using a single class Executor the user gets the functionality from both java.lang.ProcessBuilder and Apache Commons Exec, along with the ability to fork the currently running JVM process and remotely execute commands via SSH.

NOTE: If you are launching a JVM process (or running java manually setting options), and using the java11+ feature of executing as a "single file source code", and you ALSO have that class file on the classpath, you WILL get the following error:

error: class found on application class path ....

What this REALLY means is:

"error: A compiled class <fully qualified class name> already exists on
the application classpath and as a result the same class cannot be used
as a source for launching single-file source code program".

https://mail.openjdk.java.net/pipermail/jdk-dev/2018-June/001438.html

Release Notes

Examples (these are written in kotlin)

Easiest, and simplest way to get UTF8 output from running an application. This is VERY simple, and designed for quickly running, small-output applications. For anything just a hint that it might be MORE complex, use the builder pattern with the appropriate configuration.

val output = Executor.run("java", "-version")

Output is pumped to NullOutputStream

Executor().command("java", "-version").start()

Returning the exit code
Output is pumped to NullOutputStream

val exit = Executor().command("java", "-version").startBlocking().getExitValue()

Return output as UTF8 String

val output = Executor().command("java", "-version").enableRead().startBlocking().output.utf8()

Pumping the output to a logger

Executor().command("java", "-version")
    .redirectOutput(Slf4jStream.asInfo(LoggerFactory.getLogger(javaClass.name + ".MyProcess")))
    .start()

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

Executor()
    .command("java", "-version")
    .redirectOutput(Slf4jStream.asInfo())
    .start()

Pumping the output to the logger of the caller class

Executor()
    .command("java", "-version")
    .redirectOutput(Slf4jStream.asInfo())
    .start()

Pumping the output to a logger
Returning output as UTF8 String

val output = Executor()
                .command("java", "-version")
                .redirectOutput(Slf4jStream.asInfo())
                .enableRead()
                .start()
                .output.utf8()

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

val output = Executor()
                .command("java", "-version")
                .redirectError(Slf4jStream.asInfo())
                .enableRead()
                .start()
                .output.utf8()

Running with a timeout of 60 seconds
Output pumped to NullOutputStream

try {
    runBlocking {
        Executor()
            .command("java", "-version")
            .start(60, TimeUnit.SECONDS)
    }
} catch (e: TimeoutException) {
    // process is automatically destroyed
}

Pumping output to another OutputStream

Executor()
    .command("java", "-version")
    .redirectOutput(out)
    .start()

Handling output line-by-line while process is running (Version 1)

 runBlocking {
    Executor()
        .command("java", "-version")
        .redirectOutput(object : LogOutputStream() {
            override fun processLine(line: String) {
                // ...
            }
        })
        .start()
}

Handling output line-by-line while process is running (Version 2)

val result = Executor()
    .command("java", "-version")
    .enableRead()
    .startAsync()

runBlocking {
    val fullOutput = mutableListOf<String>()

    val output = result.output
    while (output.isOpen) {
        fullOutput.add(output.utf8())
    }

    val outputString: String = fullOutput.joinToString()
    Assertions.assertFalse(outputString.isEmpty())
}

Destroy the running process when VM exits
Output pumped to NullOutputStream

Executor().command("java", "-version").destroyOnExit().start()

Run process with a specific environment variable
Output pumped to NullOutputStream

Executor().command("java", "-version").environment("foo", "bar").start()

Run process with a specific environment
Output pumped to NullOutputStream

val env = mapOf<String, String>(...)
Executor()
    .command("java", "-version")
    .environment(env)
    .start()

Throw exception when wrong exit code
Output is pumped to NullOutputStream

try {
    runBlocking {
        Executor()
            .command("java", "-version")
            .exitValues(3)
            .start()
    }
} catch (e: InvalidExitValueException) {
    println("Process exited with " + e.exitValue)
}

Throw exception when wrong exit code
Return output as UTF8 String

 var output: String
try {
    output = runBlocking {
        Executor()
            .command("java", "-version")
            .enableRead()
            .exitValues(3)
            .start()
            .output.utf8()
    }
} catch (e: InvalidExitValueException) {
    println("Process exited with " + e.exitValue)
    output = (e.result as SyncProcessResult).output.utf8()
}

Starting process in the background
Output is pumped to NullOutputStream

val deferredProcess = Executor()
    .command("java", "-version")
    .startAsync()

//do some stuff..

deferredProcess.awaitBlocking(60, TimeUnit.SECONDS)

Start process in the background
Return output as UTF8 String

val deferredProcess = Executor()
    .command("java", "-version")
    .enableRead()
    .startAsync()

//do some stuff

deferredProcess.awaitBlocking(60, TimeUnit.SECONDS)

return runBlocking {
    deferredProcess.output.utf8()
}

Maven Info

<dependencies>
    ...
    <dependency>
      <groupId>com.dorkbox</groupId>
      <artifactId>Executor</artifactId>
      <version>3.14</version>
    </dependency>
</dependencies>

Gradle Info

dependencies {
    ...
    implementation("com.dorkbox:Executor:3.14")
}

License

This project is distributed under the terms of the Apache v2.0 License. See file "LICENSE" for further references.

7.7 KiB Raw Blame History