Anleitung zur java.lang.ProcessBuilder-API

1. Übersicht

Die Prozess-API bietet eine leistungsstarke Möglichkeit, Betriebssystembefehle in Java auszuführen. Es gibt jedoch mehrere Optionen, die das Arbeiten umständlich machen können.

In diesem Tutorial sehen wir uns an, wie Java dies mit der ProcessBuilder- API verringert .

2. ProcessBuilder- API

Die ProcessBuilder- Klasse bietet Methoden zum Erstellen und Konfigurieren von Betriebssystemprozessen. Mit jeder ProcessBuilder- Instanz können wir eine Sammlung von Prozessattributen verwalten . Wir können dann einen neuen Prozess mit diesen angegebenen Attributen starten .

Hier sind einige gängige Szenarien, in denen wir diese API verwenden könnten:

  • Suchen Sie die aktuelle Java-Version
  • Richten Sie eine benutzerdefinierte Schlüsselwertzuordnung für unsere Umgebung ein
  • Ändern Sie das Arbeitsverzeichnis, in dem unser Shell-Befehl ausgeführt wird
  • Leiten Sie Eingabe- und Ausgabestreams zu benutzerdefinierten Ersetzungen um
  • Erben Sie beide Streams des aktuellen JVM-Prozesses
  • Führen Sie einen Shell-Befehl aus Java-Code aus

In späteren Abschnitten werden wir uns jeweils praktische Beispiele ansehen.

Bevor wir uns jedoch mit dem Arbeitscode befassen, schauen wir uns an, welche Funktionen diese API bietet.

2.1. Methodenübersicht

In diesem Abschnitt werden wir einen Schritt zurücktreten und kurz die wichtigsten Methoden in der ProcessBuilder- Klasse betrachten . Dies wird uns helfen, wenn wir später auf einige echte Beispiele eingehen:

  • ProcessBuilder(String... command)

    Mit diesem praktischen Konstruktor können Sie einen neuen Process Builder mit dem angegebenen Betriebssystemprogramm und den angegebenen Argumenten erstellen.

  • directory(File directory)

    Wir können das Standard - Arbeitsverzeichnis des aktuellen Prozesses außer Kraft setzen , indem Sie die Aufruf Verzeichnis Methode und ein vorübergehenden Datei - Objekt. Standardmäßig ist das aktuelle Arbeitsverzeichnis auf den Wert festgelegt, der von der Systemeigenschaft user.dir zurückgegeben wird .

  • environment()

    Wenn wir die aktuellen Umgebungsvariablen abrufen möchten, können wir einfach die Umgebungsmethode aufrufen . Es gibt uns eine Kopie der aktuellen Prozessumgebung mit System.getenv () zurück, jedoch als Map .

  • inheritIO()

    Wenn wir angeben möchten, dass die Quelle und das Ziel für unsere Unterprozess-Standard-E / A mit denen des aktuellen Java-Prozesses übereinstimmen sollen , können wir die inheritIO- Methode verwenden.

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

    Wenn wir das Standardeingabe-, Ausgabe- und Fehlerziel des Process Builders in eine Datei umleiten möchten, stehen uns diese drei ähnlichen Umleitungsmethoden zur Verfügung.

  • start()

    Um einen neuen Prozess mit dem zu starten, was wir konfiguriert haben, rufen wir einfach start () auf .

Wir sollten beachten, dass diese Klasse NICHT synchronisiert ist . Wenn beispielsweise mehrere Threads gleichzeitig auf eine ProcessBuilder- Instanz zugreifen, muss die Synchronisierung extern verwaltet werden.

3. Beispiele

Nachdem wir ein grundlegendes Verständnis der ProcessBuilder- API haben, gehen wir einige Beispiele durch.

3.1. Verwenden von ProcessBuilder zum Drucken der Java-Version

In diesem ersten Beispiel führen wir den Java- Befehl mit einem Argument aus, um die Version zu erhalten .

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

Zuerst erstellen wir unser ProcessBuilder- Objekt und übergeben die Befehls- und Argumentwerte an den Konstruktor. Als nächstes starten wir den Prozess mit der Methode start () , um ein Process- Objekt abzurufen .

Nun wollen wir sehen, wie mit der Ausgabe umgegangen wird:

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

Hier lesen wir die Prozessausgabe und überprüfen den Inhalt, den wir erwarten. Im letzten Schritt warten wir, bis der Prozess mit process.waitFor () abgeschlossen ist .

Sobald der Prozess abgeschlossen ist, gibt der Rückgabewert an, ob der Prozess erfolgreich war oder nicht .

Einige wichtige Punkte, die Sie beachten sollten:

  • Die Argumente müssen in der richtigen Reihenfolge sein
  • Darüber hinaus werden in diesem Beispiel das Standardarbeitsverzeichnis und die Standardumgebung verwendet
  • Wir rufen process.waitFor () absichtlich erst auf, nachdem wir die Ausgabe gelesen haben, da der Ausgabepuffer den Prozess möglicherweise zum Stillstand bringt
  • Wir haben angenommen, dass der Java- Befehl über die Variable PATH verfügbar ist

3.2. Starten eines Prozesses mit einer geänderten Umgebung

In diesem nächsten Beispiel erfahren Sie, wie Sie die Arbeitsumgebung ändern.

Bevor wir dies tun, werfen wir zunächst einen Blick auf die Informationen, die wir in der Standardumgebung finden können :

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

Dadurch werden einfach alle standardmäßig bereitgestellten Variableneinträge ausgedruckt:

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.

Wie immer ist der vollständige Quellcode des Artikels auf GitHub verfügbar.