Ръководство за java.lang.ProcessBuilder API

1. Общ преглед

API на процеса предоставя мощен начин за изпълнение на команди на операционната система в Java. Той обаче има няколко опции, които могат да го направят тромаво да се работи.

В този урок ще разгледаме как Java облекчава това с API на ProcessBuilder .

2. API на ProcessBuilder

Класът ProcessBuilder предоставя методи за създаване и конфигуриране на процеси на операционната система. Всеки екземпляр ProcessBuilder ни позволява да управляваме колекция от атрибути на процеса . След това можем да стартираме нов процес с тези атрибути.

Ето няколко често срещани сценария, при които бихме могли да използваме този API:

  • Намерете текущата версия на Java
  • Създайте персонализирана карта ключ-стойност за нашата среда
  • Променете работната директория на мястото, където се изпълнява нашата командна команда
  • Пренасочвайте входни и изходни потоци към персонализирани замествания
  • Наследете и двата потока от текущия JVM процес
  • Изпълнете командата на черупката от Java код

Ще разгледаме практически примери за всеки от тях в следващите раздели.

Но преди да се потопим в работния код, нека да разгледаме какъв вид функционалност предоставя този API.

2.1. Резюме на метода

В този раздел ще направим крачка назад и ще разгледаме накратко най-важните методи в класа ProcessBuilder . Това ще ни помогне, когато по-късно се потопим в някои реални примери:

  • ProcessBuilder(String... command)

    За да създадем нов конструктор на процеси с посочената програма и аргументи на операционната система, можем да използваме този удобен конструктор.

  • directory(File directory)

    Можем да заменим работната директория по подразбиране на текущия процес, като извикаме метода на директорията и предадем обект File . По подразбиране текущата работна директория е зададена на стойността, върната от системното свойство user.dir .

  • environment()

    Ако искаме да получим текущите променливи на средата, можем просто да извикаме метода на средата . Той ни връща копие на текущата среда на процеса, използвайки System.getenv (), но като карта .

  • inheritIO()

    Ако искаме да посочим, че източникът и местоназначението за нашия стандартен вход / изход за подпроцеса трябва да бъдат същите като този на текущия процес на Java, можем да използваме метода наследяване на IO .

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

    Когато искаме да пренасочим стандартния вход, изход и дестинация на конструктора на процес към файл, ние разполагаме с тези три подобни метода за пренасочване.

  • start()

    Не на последно място, за да стартираме нов процес с това, което сме конфигурирали, ние просто извикваме start () .

Трябва да отбележим, че този клас НЕ е синхронизиран . Например, ако имаме няколко нишки, които едновременно имат достъп до екземпляр ProcessBuilder, тогава синхронизацията трябва да се управлява външно.

3. Примери

Сега, когато имаме основно разбиране за API на ProcessBuilder , нека разгледаме някои примери.

3.1. Използване на ProcessBuilder за отпечатване на версията на Java

В този първи пример ще изпълним командата на java с един аргумент, за да получим версията .

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

Първо, ние създаваме нашия обект ProcessBuilder, предавайки стойностите на командите и аргументите на конструктора. След това стартираме процеса, използвайки метода start () , за да получим обект Process .

Сега нека видим как да се справим с изхода:

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

Тук четем изхода на процеса и проверяваме съдържанието, което очакваме. В последната стъпка изчакваме процесът да завърши, използвайки process.waitFor () .

След като процесът приключи, връщаната стойност ни казва дали процесът е бил успешен или не .

Няколко важни точки, които трябва да имате предвид:

  • Аргументите трябва да са в правилния ред
  • Освен това в този пример се използват работната директория и средата по подразбиране
  • Умишлено не извикваме process.waitFor (), докато не прочетем изхода, защото изходният буфер може да спре процеса
  • Направихме предположението, че командата java е достъпна чрез променливата PATH

3.2. Стартиране на процес с модифицирана среда

В този следващ пример ще видим как да модифицираме работната среда.

Но преди да направим това, нека започнем, като разгледаме вида информация, която можем да намерим в средата по подразбиране :

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

Това просто отпечатва всеки от променливите записи, които са предоставени по подразбиране:

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.

Както винаги, пълният изходен код на статията е достъпен в GitHub.