java.lang
類別 ProcessBuilder

java.lang.Object
  java.lang.ProcessBuilder

public final class ProcessBuilder
extends Object

此類別用於創建作業系統進程。

每個 ProcessBuilder 實例管理一個進程屬性集。start() 方法利用這些屬性創建一個新的 Process 實例。start() 方法可以從同一實例重複調用，以利用相同的或相關的屬性創建新的子進程。

每個進程產生器管理這些進程屬性：

• 命令 是一個字元串列表，它表示要調用的外部程序檔案及其參數（如果有）。在此，表示有效的作業系統命令的字元串列表是依賴於系統的。例如，每一個總體變數，通常都要成為此列表中的元素，但有一些作業系統，希望程序能自己標記命令行字元串——在這種系統中，Java 實作可能需要命令確切地包含這兩個元素。
• 環境 是從變數 到值 的依賴於系統的映射。初始值是當前進程環境的一個副本（請參閱 System.getenv()）。
• 工作目錄。預設值是當前進程的當前工作目錄，通常根據系統屬性 user.dir 來命名。
• redirectErrorStream 屬性。最初，此屬性為 false，意思是子進程的標準輸出和錯誤輸出被發送給兩個獨立的串流，這些串流可以通過 Process.getInputStream() 和 Process.getErrorStream() 方法來存取。如果將值設置為 true，標準錯誤將與標準輸出合併。這使得關聯錯誤訊息和相應的輸出變得更容易。在此情況下，合併的資料可從 Process.getInputStream() 返回的串流讀取，而從 Process.getErrorStream() 返回的串流讀取將直接到達檔案尾。

修改進程建構器的屬性將影響後續由該物件的 start() 方法啟動的進程，但從不會影響以前啟動的進程或 Java 自身的進程。

大多數錯誤檢查由 start() 方法執行。可以修改物件的狀態，但這樣 start() 將會失敗。例如，將命令屬性設置為一個空列表將不會拋出異常，除非包含了 start()。

注意，此類別不是同步的。如果多個執行緒同時存取一個 ProcessBuilder，而其中至少一個執行緒從結構上修改了其中一個屬性，它必須 保持外部同步。

很容易啟動一個使用預設工作目錄和環境的新進程：

 Process p = new ProcessBuilder("myCommand", "myArg").start();
 

下面是一個利用修改過的工作目錄和環境啟動進程的例子：

 ProcessBuilder pb = new ProcessBuilder("myCommand", "myArg1", "myArg2");
 Map<String, String> env = pb.environment();
 env.put("VAR1", "myValue");
 env.remove("OTHERVAR");
 env.put("VAR2", env.get("VAR1") + "suffix");
 pb.directory(new File("myDir"));
 Process p = pb.start();
 

要利用一組明確的環境變數啟動進程，在添加環境變數之前，首先調用 Map.clear()。

從以下版本開始：

1.5

建構子摘要

ProcessBuilder(List<String> command)
利用指定的作業系統程序和參數建構一個進程產生器。

ProcessBuilder(String... command)
利用指定的作業系統程序和參數建構一個進程產生器。

方法摘要

List<String>	command() 返回此進程產生器的作業系統程序和參數。
ProcessBuilder	command(List<String> command) 設置此進程產生器的作業系統程序和參數。
ProcessBuilder	command(String... command) 設置此進程產生器的作業系統程序和參數。
File	directory() 返回此進程產生器的工作目錄。
ProcessBuilder	directory(File directory) 設置此進程產生器的工作目錄。
Map<String,String>	environment() 返回此進程產生器環境的字元串映射視圖。
boolean	redirectErrorStream() 通知進程產生器是否合併標準錯誤和標準輸出。
ProcessBuilder	redirectErrorStream(boolean redirectErrorStream) 設置此進程產生器的 redirectErrorStream 屬性。
Process	start() 使用此進程產生器的屬性啟動一個新進程。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

建構子詳細資訊

ProcessBuilder

public ProcessBuilder(List<String> command)

利用指定的作業系統程序和參數建構一個進程產生器。此建構子不會 製作一份 command 列表的副本。後續列表更新將在進程產生器的狀態中反映出來。不必檢查 command 是否為一個有效的作業系統命令。

參數：

command - 套件含程序及其參數的列表

拋出：

NullPointerException - 如果參數為 null

ProcessBuilder

public ProcessBuilder(String... command)

利用指定的作業系統程序和參數建構一個進程產生器。這是一個有用的建構子，它將進程產生器的命令設置為與 command 陣列包含相同字元串的字元串列表，且順序相同。不必檢查 command 是否為一個有效的作業系統命令。

參數：

command - 套件含程序及其參數的字元串陣列

方法詳細資訊

command

public ProcessBuilder command(List<String> command)

設置此進程產生器的作業系統程序和參數。此方法不會 製作一份 command 列表的副本。後續列表更新將在進程產生器的狀態中反映出來。不必檢查 command 是否為一個有效的作業系統命令。

參數：

command - 套件含程序及其參數的列表

返回：

此進程產生器

拋出：

NullPointerException - 如果參數為 null

command

public ProcessBuilder command(String... command)

設置此進程產生器的作業系統程序和參數。這是一個有用的方法，它將命令設置為與 command 陣列包含相同字元串的字元串列表，且順序相同。不必檢查 command 是否為一個有效的作業系統命令。

參數：

command - 套件含程序及其參數的字元串陣列

返回：

此進程產生器

command

public List<String> command()

返回此進程產生器的作業系統程序和參數。該返回的列表不是 一份副本。後續列表更新將在此進程產生器的狀態中反映出來。

返回：

此進程產生器的程序及其參數

environment

public Map<String,String> environment()

返回此進程產生器環境的字元串映射視圖。 無論進程產生器何時創建，都需要將環境初始化為一份當前進程環境的副本（請參閱 System.getenv()）。由此物件的 start() 方法啟動的後續子進程將使用這一映射作為它們的環境。

可以使用普通的 Map 操作來修改返回的物件。對於通過 start() 方法啟動的子進程，這些修改是可見的。兩個 ProcessBuilder 實例總是包含獨立的進程環境，因此，針對返回的映射的更改從不會在任何其他 ProcessBuilder 實例或由 System.getenv 返回的值中反映出來。

如果系統不支持環境變數，將返回空映射。

返回的映射不允許空鍵或空值。試圖插入空鍵或空值或者試圖查詢它們的存在，都將拋出 NullPointerException。試圖查詢非 String 型別的鍵或值的存在，都將拋出 ClassCastException。

返回的映射的行為取決於系統。系統可能不允許修改環境變數或禁止某些變數名或變數值。出於此原因，如果不允許作業系統修改的話，試圖修改映射可能失敗，並拋出 UnsupportedOperationException 或 IllegalArgumentException。

由於環境變數名和值的外部格式取決於系統，在它們與 Java 的 Unicode 字元串之間不可能是一對一映射。此外，映射以這種方式實作：不能由 Java 程式碼修改的環境變數在子進程中將有一個不可修改的本機表示形式。

返回的映射及其集合視圖不能遵守 Object.equals(java.lang.Object) 和 Object.hashCode() 方法的常規協定。

返回的映射通常在所有平臺上都是區分大小寫的。

如果安全管理器存在，則其 checkPermission 方法通過 RuntimePermission("getenv.*") 權限進行調用。這可能導致拋出 SecurityException。

當將資訊傳遞給 Java 子進程時，系統屬性通常優先於環境變數。

返回：

此進程產生器的環境

拋出：

SecurityException - 如果安全管理器存在並且其 checkPermission 方法不允許存取進程環境

另請參見：

Runtime.exec(String[],String[],java.io.File), System.getenv()

directory

public File directory()

返回此進程產生器的工作目錄。由此物件的 start() 方法啟動的後續子進程將使用此目錄作為它們的工作目錄。返回值可以為 null，這意味著要使用當前 Java 進程的工作目錄，通常是由系統屬性 user.dir 指定的目錄作為子進程的工作目錄。

返回：

此進程產生器的工作目錄

directory

public ProcessBuilder directory(File directory)

設置此進程產生器的工作目錄。 由此物件的 start() 方法啟動的後續子進程將使用此目錄作為它們的工作目錄。參數可以為 null，這意味著要使用當前 Java 進程的工作目錄，通常是由系統屬性 user.dir 指定的目錄作為子進程的工作目錄。

參數：

directory - 新的工作目錄

返回：

此進程產生器

redirectErrorStream

public boolean redirectErrorStream()

通知進程產生器是否合併標準錯誤和標準輸出。

如果此屬性為 true，則任何由通過此物件的 start() 方法啟動的後續子進程產生的錯誤輸出都將與標準輸出合併，因此兩者均可使用 Process.getInputStream() 方法讀取。這使得關聯錯誤訊息和相應的輸出變得更容易。初始值為 false。

返回：

此進程產生器的 redirectErrorStream 屬性

redirectErrorStream

public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)

設置此進程產生器的 redirectErrorStream 屬性。

如果此屬性為 true，則任何由通過此物件的 start() 方法啟動的後續子進程產生的錯誤輸出都將與標準輸出合併，因此兩者均可使用 Process.getInputStream() 方法讀取。這使得關聯錯誤訊息和相應的輸出變得更容易。初始值為 false。

參數：

redirectErrorStream - 新的屬性值

返回：

此進程產生器

start

public Process start()
              throws IOException

使用此進程產生器的屬性啟動一個新進程。

在 directory() 指定的工作目錄中，利用 environment() 指定的進程環境，新進程將調用由 command() 給出的命令和參數。

此方法檢查命令是否為一條有效的作業系統命令。哪條命令是有效的呢？這取決於系統，但至少命令必須是非空(null)字元串的非空(null)列表。

如果有安全管理器，則用此物件的 command 陣列的首個元素作為其參數來調用安全管理器的 checkExec 方法。這可能導致拋出 SecurityException。

啟動作業系統進程的方式完全取決於系統。其中有很多方面會導致錯誤：

• 未找到作業系統程序檔案。
• 對程序檔案的存取被拒絕。
• 工作目錄不存在。

在這些情況中將會拋出一個異常。該異常的具體本質取決於系統，但它總是 IOException 的一個子類別。

針對此進程產生器的後續修改將不會影響返回的 Process。

返回：

一個新的 Process 物件，用於管理子進程

拋出：

NullPointerException - 如果命令列表的元素為空

IndexOutOfBoundsException - 如果命令是一個空列表（大小為 0）

SecurityException - 如果安全管理器存在並且其 checkExec 方法不允許創建子進程

IOException - 如果發生 I/O 錯誤

另請參見：

Runtime.exec(String[], String[], java.io.File), SecurityManager.checkExec(String)