Guide de l'API java.lang.ProcessBuilder

1. Vue d'ensemble

L'API Process fournit un moyen puissant d'exécuter des commandes du système d'exploitation en Java. Cependant, il dispose de plusieurs options qui peuvent le rendre fastidieux.

Dans ce didacticiel, nous examinerons comment Java atténue cela avec l' API ProcessBuilder .

2. API ProcessBuilder

La classe ProcessBuilder fournit des méthodes pour créer et configurer les processus du système d'exploitation. Chaque instance ProcessBuilder nous permet de gérer une collection d'attributs de processus . Nous pouvons alors démarrer un nouveau processus avec ces attributs donnés.

Voici quelques scénarios courants dans lesquels nous pourrions utiliser cette API:

  • Rechercher la version Java actuelle
  • Configurer une carte clé-valeur personnalisée pour notre environnement
  • Changer le répertoire de travail où s'exécute notre commande shell
  • Rediriger les flux d'entrée et de sortie vers des remplacements personnalisés
  • Hériter des deux flux du processus JVM actuel
  • Exécuter une commande shell à partir du code Java

Nous examinerons des exemples pratiques pour chacun d'entre eux dans les sections suivantes.

Mais avant de plonger dans le code de travail, examinons le type de fonctionnalité fourni par cette API.

2.1. Résumé de la méthode

Dans cette section, nous allons prendre du recul et examiner brièvement les méthodes les plus importantes de la classe ProcessBuilder . Cela nous aidera lorsque nous nous plongerons dans de vrais exemples plus tard:

  • ProcessBuilder(String... command)

    Pour créer un nouveau générateur de processus avec le programme et les arguments du système d'exploitation spécifié, nous pouvons utiliser ce constructeur pratique.

  • directory(File directory)

    Nous pouvons remplacer le répertoire de travail par défaut du processus actuel en appelant la méthode de répertoire et en passant un objet File . Par défaut, le répertoire de travail actuel est défini sur la valeur renvoyée par la propriété système user.dir .

  • environment()

    Si nous voulons obtenir les variables d'environnement actuelles, nous pouvons simplement appeler la méthode d' environnement . Il nous renvoie une copie de l'environnement de processus actuel en utilisant System.getenv () mais sous forme de Map .

  • inheritIO()

    Si nous voulons spécifier que la source et la destination de nos E / S standard de sous-processus doivent être les mêmes que celles du processus Java actuel, nous pouvons utiliser la méthode inheritIO .

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

    Lorsque nous voulons rediriger l'entrée, la sortie et la destination d'erreur standard du générateur de processus vers un fichier, nous avons ces trois méthodes de redirection similaires à notre disposition.

  • start()

    Dernier point mais non le moindre, pour démarrer un nouveau processus avec ce que nous avons configuré, nous appelons simplement start () .

Il faut noter que cette classe n'est PAS synchronisée . Par exemple, si plusieurs threads accèdent simultanément à une instance ProcessBuilder, la synchronisation doit être gérée en externe.

3. Exemples

Maintenant que nous avons une compréhension de base de l' API ProcessBuilder , passons en revue quelques exemples.

3.1. Utilisation de ProcessBuilder pour imprimer la version de Java

Dans ce premier exemple, nous allons exécuter la commande java avec un argument afin d'obtenir la version .

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

Tout d'abord, nous créons notre objet ProcessBuilder en transmettant les valeurs de commande et d'argument au constructeur. Ensuite, nous démarrons le processus en utilisant la méthode start () pour obtenir un objet Process .

Voyons maintenant comment gérer la sortie:

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);

Ici, nous lisons la sortie du processus et la vérification du contenu est ce que nous attendons. Dans la dernière étape, nous attendons que le processus se termine en utilisant process.waitFor () .

Une fois le processus terminé, la valeur de retour nous indique si le processus a réussi ou non .

Quelques points importants à garder à l'esprit:

  • Les arguments doivent être dans le bon ordre
  • Moreover, in this example, the default working directory and environment are used
  • We deliberately don't call process.waitFor() until after we've read the output because the output buffer might stall the process
  • We've made the assumption that the java command is available via the PATH variable

3.2. Starting a Process With a Modified Environment

In this next example, we're going to see how to modify the working environment.

But before we do that let's begin by taking a look at the kind of information we can find in the default environment:

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

This simply prints out each of the variable entries which are provided by default:

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.

Comme toujours, le code source complet de l'article est disponible à l'adresse over sur GitHub.