Guía de la API java.lang.ProcessBuilder

1. Información general

La API de proceso proporciona una forma poderosa de ejecutar comandos del sistema operativo en Java. Sin embargo, tiene varias opciones que pueden dificultar el trabajo.

En este tutorial, veremos cómo Java alivia eso con la API de ProcessBuilder .

2. API de ProcessBuilder

La clase ProcessBuilder proporciona métodos para crear y configurar procesos del sistema operativo. Cada instancia de ProcessBuilder nos permite administrar una colección de atributos de proceso . Luego podemos comenzar un nuevo proceso con esos atributos dados.

A continuación, se muestran algunos escenarios comunes en los que podríamos usar esta API:

  • Encuentra la versión actual de Java
  • Configurar un mapa de clave-valor personalizado para nuestro entorno
  • Cambiar el directorio de trabajo de donde se ejecuta nuestro comando de shell
  • Redirigir flujos de entrada y salida a reemplazos personalizados
  • Heredar los dos flujos del proceso JVM actual
  • Ejecute un comando de shell desde el código Java

Veremos ejemplos prácticos para cada uno de estos en secciones posteriores.

Pero antes de sumergirnos en el código de trabajo, echemos un vistazo a qué tipo de funcionalidad proporciona esta API.

2.1. Resumen del método

En esta sección, daremos un paso atrás y veremos brevemente los métodos más importantes de la clase ProcessBuilder . Esto nos ayudará cuando nos sumerjamos en algunos ejemplos reales más adelante:

  • ProcessBuilder(String... command)

    Para crear un nuevo generador de procesos con el programa y los argumentos del sistema operativo especificado, podemos usar este conveniente constructor.

  • directory(File directory)

    Podemos anular el directorio de trabajo predeterminado del proceso actual llamando al método de directorio y pasando un objeto File . De forma predeterminada, el directorio de trabajo actual se establece en el valor devuelto por la propiedad del sistema user.dir .

  • environment()

    Si queremos obtener las variables de entorno actuales, simplemente podemos llamar al método de entorno . Nos devuelve una copia del entorno de proceso actual usando System.getenv () pero como un mapa .

  • inheritIO()

    Si queremos especificar que el origen y el destino de nuestra E / S estándar de subproceso deben ser los mismos que los del proceso Java actual, podemos usar el método hereitIO .

  • redirectInput(File file), redirectOutput(File file), redirectError(File file)

    Cuando queremos redirigir la entrada, salida y destino de error estándar del generador de procesos a un archivo, tenemos estos tres métodos de redirección similares a nuestra disposición.

  • start()

    Por último, pero no menos importante, para iniciar un nuevo proceso con lo que hemos configurado, simplemente llamamos a start () .

Debemos tener en cuenta que esta clase NO está sincronizada . Por ejemplo, si tenemos varios subprocesos que acceden a una instancia de ProcessBuilder al mismo tiempo, la sincronización debe administrarse externamente.

3. Ejemplos

Ahora que tenemos una comprensión básica de la API de ProcessBuilder , veamos algunos ejemplos.

3.1. Uso de ProcessBuilder para imprimir la versión de Java

En este primer ejemplo, ejecutaremos el comando java con un argumento para obtener la versión .

Process process = new ProcessBuilder("java", "-version").start();

Primero, creamos nuestro objeto ProcessBuilder pasando el comando y los valores del argumento al constructor. A continuación, comenzamos el proceso usando el método start () para obtener un objeto Process .

Ahora veamos cómo manejar la salida:

List results = readOutput(process.getInputStream()); assertThat("Results should not be empty", results, is(not(empty()))); assertThat("Results should contain java version: ", results, hasItem(containsString("java version"))); int exitCode = process.waitFor(); assertEquals("No errors should be detected", 0, exitCode);

Aquí estamos leyendo el resultado del proceso y verificando que el contenido sea el esperado. En el paso final, esperamos que el proceso termine usando process.waitFor () .

Una vez que el proceso ha terminado, el valor de retorno nos dice si el proceso fue exitoso o no .

Algunos puntos importantes a tener en cuenta:

  • Los argumentos deben estar en el orden correcto
  • Además, en este ejemplo, se utilizan el directorio de trabajo y el entorno predeterminados
  • Deliberadamente no llamamos a process.waitFor () hasta que hayamos leído la salida porque el búfer de salida puede detener el proceso.
  • Hemos asumido que el comando java está disponible a través de la variable PATH

3.2. Inicio de un proceso con un entorno modificado

En el siguiente ejemplo, veremos cómo modificar el entorno de trabajo.

Pero antes de hacer eso, comencemos por echar un vistazo al tipo de información que podemos encontrar en el entorno predeterminado :

ProcessBuilder processBuilder = new ProcessBuilder(); Map environment = processBuilder.environment(); environment.forEach((key, value) -> System.out.println(key + value));

Esto simplemente imprime cada una de las entradas de variables que se proporcionan de forma predeterminada:

PATH/usr/bin:/bin:/usr/sbin:/sbin SHELL/bin/bash ...

Now we're going to add a new environment variable to our ProcessBuilder object and run a command to output its value:

environment.put("GREETING", "Hola Mundo"); processBuilder.command("/bin/bash", "-c", "echo $GREETING"); Process process = processBuilder.start();

Let’s decompose the steps to understand what we've done:

  • Add a variable called ‘GREETING' with a value of ‘Hola Mundo' to our environment which is a standard Map
  • This time, rather than using the constructor we set the command and arguments via the command(String… command) method directly.
  • We then start our process as per the previous example.

To complete the example, we verify the output contains our greeting:

List results = readOutput(process.getInputStream()); assertThat("Results should not be empty", results, is(not(empty()))); assertThat("Results should contain java version: ", results, hasItem(containsString("Hola Mundo")));

3.3. Starting a Process With a Modified Working Directory

Sometimes it can be useful to change the working directory. In our next example we're going to see how to do just that:

@Test public void givenProcessBuilder_whenModifyWorkingDir_thenSuccess() throws IOException, InterruptedException { ProcessBuilder processBuilder = new ProcessBuilder("/bin/sh", "-c", "ls"); processBuilder.directory(new File("src")); Process process = processBuilder.start(); List results = readOutput(process.getInputStream()); assertThat("Results should not be empty", results, is(not(empty()))); assertThat("Results should contain directory listing: ", results, contains("main", "test")); int exitCode = process.waitFor(); assertEquals("No errors should be detected", 0, exitCode); }

In the above example, we set the working directory to the project's src dir using the convenience method directory(File directory). We then run a simple directory listing command and check that the output contains the subdirectories main and test.

3.4. Redirecting Standard Input and Output

In the real world, we will probably want to capture the results of our running processes inside a log file for further analysis. Luckily the ProcessBuilder API has built-in support for exactly this as we will see in this example.

By default, our process reads input from a pipe. We can access this pipe via the output stream returned by Process.getOutputStream().

However, as we'll see shortly, the standard output may be redirected to another source such as a file using the method redirectOutput. In this case, getOutputStream() will return a ProcessBuilder.NullOutputStream.

Let's return to our original example to print out the version of Java. But this time let's redirect the output to a log file instead of the standard output pipe:

ProcessBuilder processBuilder = new ProcessBuilder("java", "-version"); processBuilder.redirectErrorStream(true); File log = folder.newFile("java-version.log"); processBuilder.redirectOutput(log); Process process = processBuilder.start();

In the above example, we create a new temporary file called log and tell our ProcessBuilder to redirect output to this file destination.

In this last snippet, we simply check that getInputStream() is indeed null and that the contents of our file are as expected:

assertEquals("If redirected, should be -1 ", -1, process.getInputStream().read()); List lines = Files.lines(log.toPath()).collect(Collectors.toList()); assertThat("Results should contain java version: ", lines, hasItem(containsString("java version")));

Now let's take a look at a slight variation on this example. For example when we wish to append to a log file rather than create a new one each time:

File log = tempFolder.newFile("java-version-append.log"); processBuilder.redirectErrorStream(true); processBuilder.redirectOutput(Redirect.appendTo(log));

It's also important to mention the call to redirectErrorStream(true). In case of any errors, the error output will be merged into the normal process output file.

We can, of course, specify individual files for the standard output and the standard error output:

File outputLog = tempFolder.newFile("standard-output.log"); File errorLog = tempFolder.newFile("error.log"); processBuilder.redirectOutput(Redirect.appendTo(outputLog)); processBuilder.redirectError(Redirect.appendTo(errorLog));

3.5. Inheriting the I/O of the Current Process

In this penultimate example, we'll see the inheritIO() method in action. We can use this method when we want to redirect the sub-process I/O to the standard I/O of the current process:

@Test public void givenProcessBuilder_whenInheritIO_thenSuccess() throws IOException, InterruptedException { ProcessBuilder processBuilder = new ProcessBuilder("/bin/sh", "-c", "echo hello"); processBuilder.inheritIO(); Process process = processBuilder.start(); int exitCode = process.waitFor(); assertEquals("No errors should be detected", 0, exitCode); }

In the above example, by using the inheritIO() method we see the output of a simple command in the console in our IDE.

In the next section, we're going to take a look at what additions were made to the ProcessBuilder API in Java 9.

4. Java 9 Additions

Java 9 introduced the concept of pipelines to the ProcessBuilder API:

public static List startPipeline​(List builders) 

Using the startPipeline method we can pass a list of ProcessBuilder objects. This static method will then start a Process for each ProcessBuilder. Thus, creating a pipeline of processes which are linked by their standard output and standard input streams.

For example, if we want to run something like this:

find . -name *.java -type f | wc -l

What we'd do is create a process builder for each isolated command and compose them into a pipeline:

@Test public void givenProcessBuilder_whenStartingPipeline_thenSuccess() throws IOException, InterruptedException { List builders = Arrays.asList( new ProcessBuilder("find", "src", "-name", "*.java", "-type", "f"), new ProcessBuilder("wc", "-l")); List processes = ProcessBuilder.startPipeline(builders); Process last = processes.get(processes.size() - 1); List output = readOutput(last.getInputStream()); assertThat("Results should not be empty", output, is(not(empty()))); }

In this example, we're searching for all the java files inside the src directory and piping the results into another process to count them.

To learn about other improvements made to the Process API in Java 9, check out our great article on Java 9 Process API Improvements.

5. Conclusion

To summarize, in this tutorial, we’ve explored the java.lang.ProcessBuilder API in detail.

First, we started by explaining what can be done with the API and summarized the most important methods.

Next, we took a look at a number of practical examples. Finally, we looked at what new additions were introduced to the API in Java 9.

Como siempre, el código fuente completo del artículo está disponible en GitHub.