java-processes

This is a small library to help you create and (automatically kill) Java processes from within Java. This is useful in a number of situations:

• Some part of your program needs different JVM args, a different classpath, or even a different JVM.
• You want to safely execute code that may run out of memory.
• You want to execute multiple instances of legacy code with global state in parallel.

To start part of your Java program in a separate JVM, simply write:

Process proc = new JavaProcessBuilder(SomeClass.class, "some", "args").start();

That's it! This snippet will start a new JVM with SomeClass as the main class, passing "some" and "args" as arguments. No need to specify the classpath, the VM args, or the path to the Java executable; these are all taken from the JVM in which your program is running!

Configuration

JavaProcessBuilder makes it very simple to configure the classpath, the VM args, or the Java executable, if you want them to be different from those of the parent JVM:

Process proc = new JavaProcessBuilder(SomeClass.class)
        .javaHome("/different/java/")
        .classpath("some-classes.jar")
        .vmArgs("-ea", "-Xmx8g")
        .start();

If you know the ProcessBuilder class from the Java Standard Library, you may also know that lets you specify a number of additional options when starting a process, such as environment variables, working directory, or I/O behavior. JavaProcessBuilder is actually built on top of ProcessBuilder, so you can configure all of these things too:

Process proc = new JavaProcessBuilder(SomeClass.class)
        .classpath("some-classes.jar")
        .build()
        .directory(new File("test"))
        .inheritIO()
        .start();

What is happening here is that build() returns a ProcessBuilder instance that has all the JVM-specific configuration imprinted and can then be further configured. In fact, the JavaProcessBuilder.start() method is simply a shorthand for build().start().

Automatically Killing Child Processes

One thing that is annoying when executing parts of your program in separate JVMs is that they continue to run when you kill the parent process (especially during debugging). This library comes with two mechanism that can help you with that.

AutoProcessKiller

The first mechanism is based on shutdown hooks and can be used in the following way:

new AutoProcessKiller().add(process);

Now, when the JVM shuts down, the AutoProcessKiller (which is a Thread) is executed and kills the process (if it is still running). However, this will not work if the JVM is terminated forcibly, which happens, for example, if you press the stop button in Eclipse. In this case, the shutdown hooks may not be executed, so the child processes may continue to run. In fact, I think any mechanism to kill child processes from within the parent JVM is doomed to suffer from this problem.

AutoExit

This is why this library comes with a second mechanism, which works from within the child VM and is guaranteed to kill the child process as soon as the parent process stops running (for whatever reason). You can use it by calling

AutoExit.install();

in the child VM. Or, to make it even simpler, you can call autoExit(true) on the process builder instance that you use to start the child VM:

Process proc = new JavaProcessBuilder(SomeClass.class).autoExit(true).start();

In this case, the process builder will use the AutoExitProgram class as the actual main class, which in turn calls AutoExit.install() and then calls SomeClass.main().

This mechanism is based on a simple trick: AutoExit (being a separate thread) calls System.in.read(), which only returns once the parent process terminates. As soon as this happens, System.exit() is called. Note, however, that this trick does not work if you need to use System.in for something else in the child process. In that case, you should use the first mechanism.