Shell, JVM, and SSH command execution on Linux, MacOS, or Windows for Java 11+ and Kotlin
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Go to file
Robinson 9aa1594330
updated version
1 week ago
gradle/wrapper updated gradle version 1 week ago
src/dorkbox/executor updated version 1 week ago
src9 Fixed JvmHelper to have passed in parameters for mac/windows, isntead of accessing via Executor class 1 year ago
test/dorkbox Fixed file name 1 year ago
test9/dorkbox Fixed java9 unit tests for junit5 1 year ago
.gitignore Updated to use Gradle Utils for gradle/project update management 4 years ago
LICENSE updated build deps 1 week ago
LICENSE.Apachev2 Moved shell executor from utils to it's own project 5 years ago
LICENSE.CC0 Cleaned up license 3 years ago
LICENSE.MIT Added/updated license files 3 years ago
README.md updated version 1 week ago
build.gradle.kts updated version 1 week ago
gradle.properties updated gradle build properties 1 year ago
gradlew updated gradle version 1 week ago
gradlew.bat Updated gradle to 7.2 1 year ago
settings.gradle.kts removed sorting 1 week ago

README.md

Executor

Dorkbox Github Gitlab

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:

  1. Redirecting in/out/err streams correctly
  2. Enable reading a single-character from the console input-stream
  3. Correctly reading out/err process output streams to prevent memory and threading issues
  4. Executing a JVM process using the same JVM as is currently running
  5. Executing remote processes via SSH
  6. Using and supporting kotlin co-routines for thread suspension
  7. 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")
            .timeout(60, TimeUnit.SECONDS)
            .start()
    }
} 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.12</version>
    </dependency>
</dependencies>

Gradle Info

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

License

This project is © 2021 dorkbox llc, with modifications from software copyright 2014 ZeroTurnaround, and 2014 The Apache Software Foundation.

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