ch.vorburger.exec
If you like/use this project, a Star / Watch / Follow me on GitHub is appreciated!
This project is a small library allowing to launch external processes from Java code in the background, and conveniently correctly pipe their output e.g. into slf4j, await either their termination or specific output, etc.
Release Notes are in CHANGES.md.
Usage
Launching external processes from Java using the raw java.lang.ProcessBuilder API directly can be a little cumbersome. Apache Commons Exec makes it a bit easier, but lacks some convenience. This library makes it truly convenient:
ManagedProcessBuilder pb = new ManagedProcessBuilder("someExec")
.addArgument("arg1")
.setWorkingDirectory(new File("/tmp"))
.getEnvironment().put("ENV_VAR", "...")
.setDestroyOnShutdown(true)
.addStdOut(new BufferedOutputStream(new FileOutputStream(outputFile)))
.setConsoleBufferMaxLines(7000); // used by startAndWaitForConsoleMessageMaxMs
ManagedProcess p = pb.build();
p.start();
p.isAlive();
p.waitForExit();
// OR: p.waitForExitMaxMsOrDestroy(5000);
// OR: p.startAndWaitForConsoleMessageMaxMs("Successfully started", 3000);
p.exitValue();
// OR: p.destroy();
// This works even while it's running, not just when it exited
String output = p.getConsole();
If you need to, you can also attach a listener to get notified when the external process ends, by using setProcessListener() on the ManagedProcessBuilder with a ManagedProcessListener that implements onProcessComplete() and onProcessFailed().
We currently internally use Apache Commons Exec by building on top, extending and wrapping it, but without exposing this in its API, so that theoretically in the future this implementation detail could be changed.
Advantages
- automatically logs external process's STDOUT and STDERR using SLF4j out of the box (can be customized)
- automatically logs and throws for common errors (e.g. executable not found), instead of silently ignoring like j.l.Process
- automatically destroys external process with JVM shutdown hook (can be disabled)
- lets you await appearance of certain messages on the console
- lets you write tests against the expected output
History
Historically, this code was part of MariaDB4j (and this is why it's initial version was 3.0.0), but was it later split into a separate project. This was done to make it usable in separate projects (originally to launch Ansible Networking CLI commands from OpenDaylight, later to manage etcd servers in tests, both from OpenDaylight).
Similarly
For the exec functionality, zt-exec (with zt-process-killer) is similar (but refused to backlink us).
NuProcess is another similar library in the sams space.
For the expect-like functionality, from https://en.wikipedia.org/wiki/Expect#Java, note (in no particular order):
- http://expectj.sourceforge.net
- https://github.com/cverges/expect4j
- https://github.com/Alexey1Gavrilov/ExpectIt
- https://github.com/iTransformers/expect4java
- https://github.com/ronniedong/Expect-for-Java
Release
First test that GPG is set up correctly (gpg: no default secret key: No secret key gpg: signing failed: No secret key), and that the settings.xml has the credz for oss.sonatype.org (status: 401 unauthorized):
mvn verify -Pgpg
mvn deploy
Once that works, the next release can be done similarly similarly to https://github.com/vorburger/MariaDB4j#release:
mvn release:prepare
mvn release:perform -Pgpg
mvn release:clean
git push
If mvn release:prepare fails with the following error, then comment out forceSignAnnotated = true under [tag] in ~/.gitconfig:
The git-tag command failed.
[ERROR] Command output:
[ERROR] error: gpg failed to sign the data
[ERROR] error: unable to sign the tag
ToDo
This library is currently used to control daemon style external executables. To launch a process which returns binary (or massive textual) output to its STDOUT (and, presumably, have that piped into a java.io.OutputStream), it would need some tweaks. This would include making the enabled-by-default logging into slf4j, and the built-in startAndWaitForConsoleMessageMaxMs which collects output, a more configurable option.
Contributions & patches more than welcome!
5 Dec 27, 2022
20 Nov 29, 2022
4 Oct 25, 2021
1 Jan 4, 2022
6 Dec 16, 2022
16.6k Dec 30, 2022
2 Nov 19, 2017
26 Nov 15, 2022
7 Nov 8, 2022
14 Nov 17, 2022
27 Jun 13, 2022
7 Feb 5, 2022
9 Nov 10, 2022
3 Jan 31, 2022
44 Nov 12, 2022
4 Dec 29, 2021
32 Dec 15, 2022
2 Apr 18, 2022