Panduan untuk java.lang.ProcessBuilder API

1. Ikhtisar

Process API menyediakan cara yang ampuh untuk menjalankan perintah sistem operasi di Java. Namun, ia memiliki beberapa opsi yang dapat membuatnya tidak praktis untuk digunakan.

Dalam tutorial ini, kita akan melihat bagaimana Java meringankannya dengan API ProcessBuilder .

2. API ProcessBuilder

Kelas ProcessBuilder menyediakan metode untuk membuat dan mengkonfigurasi proses sistem operasi. Setiap instance ProcessBuilder memungkinkan kita untuk mengelola kumpulan atribut proses . Kami kemudian dapat memulai Proses baru dengan atribut yang diberikan tersebut.

Berikut adalah beberapa skenario umum di mana kami dapat menggunakan API ini:

  • Temukan versi Java saat ini
  • Siapkan peta nilai kunci khusus untuk lingkungan kita
  • Ubah direktori kerja tempat perintah shell kami dijalankan
  • Alihkan aliran input dan output ke penggantian kustom
  • Mewarisi kedua aliran dari proses JVM saat ini
  • Jalankan perintah shell dari kode Java

Kami akan melihat contoh praktis untuk masing-masing ini di bagian selanjutnya.

Tetapi sebelum kita menyelami kode yang berfungsi, mari kita lihat fungsionalitas seperti apa yang disediakan API ini.

2.1. Ringkasan Metode

Di bagian ini, kita akan mundur selangkah dan melihat secara singkat metode paling penting di kelas ProcessBuilder . Ini akan membantu kita saat kita mempelajari beberapa contoh nyata nanti:

  • ProcessBuilder(String... command)

    Untuk membuat pembangun proses baru dengan program sistem operasi dan argumen yang ditentukan, kita dapat menggunakan konstruktor praktis ini.

  • directory(File directory)

    Kita dapat mengganti direktori kerja default dari proses saat ini dengan memanggil metode direktori dan meneruskan objek File . Secara default, direktori kerja saat ini disetel ke nilai yang dikembalikan oleh properti sistem user.dir .

  • environment()

    Jika kita ingin mendapatkan variabel lingkungan saat ini, kita cukup memanggil metode lingkungan . Ini mengembalikan kita salinan lingkungan proses saat ini menggunakan System.getenv () tetapi sebagai Peta .

  • inheritIO()

    Jika kita ingin menentukan bahwa sumber dan tujuan untuk I / O standar subproses kita harus sama dengan proses Java saat ini, kita dapat menggunakan metode inheritIO .

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

    Saat kami ingin mengarahkan tujuan input, output, dan kesalahan standar pembangun proses ke file, kami memiliki tiga metode pengalihan serupa yang dapat kami gunakan.

  • start()

    Terakhir, untuk memulai proses baru dengan apa yang telah kita konfigurasikan, kita cukup memanggil start () .

Kita harus mencatat bahwa kelas ini TIDAK disinkronkan . Misalnya, jika kita memiliki beberapa utas yang mengakses instance ProcessBuilder secara bersamaan, maka sinkronisasi harus dikelola secara eksternal.

3. Contoh

Sekarang setelah kita memiliki pemahaman dasar tentang ProcessBuilder API, mari kita lihat beberapa contoh.

3.1. Menggunakan ProcessBuilder untuk Mencetak Versi Java

Dalam contoh pertama ini, kita akan menjalankan perintah java dengan satu argumen untuk mendapatkan versinya .

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

Pertama, kita membuat objek ProcessBuilder yang meneruskan nilai perintah dan argumen ke konstruktor. Selanjutnya, kita memulai proses menggunakan metode start () untuk mendapatkan objek Proses .

Sekarang mari kita lihat bagaimana menangani output:

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

Di sini kita membaca keluaran proses dan memverifikasi isinya sesuai dengan yang kita harapkan. Pada langkah terakhir, kita menunggu proses selesai menggunakan process.waitFor () .

Setelah proses selesai, nilai kembalian memberi tahu kita apakah proses itu berhasil atau tidak .

Beberapa poin penting yang perlu diingat:

  • Argumen harus dalam urutan yang benar
  • Selain itu, dalam contoh ini, direktori dan lingkungan kerja default digunakan
  • Kami sengaja tidak memanggil process.waitFor () hingga setelah kami membaca output karena buffer output mungkin menghentikan proses
  • Kami telah membuat asumsi bahwa perintah java tersedia melalui variabel PATH

3.2. Memulai Proses Dengan Lingkungan yang Dimodifikasi

Dalam contoh berikut ini, kita akan melihat bagaimana memodifikasi lingkungan kerja.

Tetapi sebelum kita melakukannya, mari kita mulai dengan melihat jenis informasi yang dapat kita temukan di lingkungan default :

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

Ini hanya mencetak setiap entri variabel yang disediakan secara 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.

Seperti biasa, kode sumber lengkap artikel tersedia di GitHub.