Question

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("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(Filedirectory) 设置此进程生成器的工作目录。
Map<String,String>	environment() 返回此进程生成器环境的字符串映射视图。
boolean	redirectErrorStream() 通知进程生成器是否合并标准错误和标准输出。
ProcessBuilder	redirectErrorStream(booleanredirectErrorStream) 设置此进程生成器的 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(Filedirectory)

设置此进程生成器的工作目录。 由此对象的 start() 方法启动的后续子进程将使用此目录作为它们的工作目录。参数可以为 null ——这意味着要使用当前 Java 进程的工作目录，通常是由系统属性 user.dir 指定的目录作为子进程的工作目录。

参数：

directory - 新的工作目录

返回：

此进程生成器

---

redirectErrorStream

public boolean redirectErrorStream()

通知进程生成器是否合并标准错误和标准输出。

如果此属性为 true ，则任何由通过此对象的 start() 方法启动的后续子进程生成的错误输出都将与标准输出合并，因此两者均可使用 Process.getInputStream() 方法读取。这使得关联错误消息和相应的输出变得更容易。初始值为 false 。

返回：

此进程生成器的 redirectErrorStream 属性

---

redirectErrorStream

public ProcessBuilder redirectErrorStream(booleanredirectErrorStream)

设置此进程生成器的 redirectErrorStream 属性。

如果此属性为 true ，则任何由通过此对象的 start() 方法启动的后续子进程生成的错误输出都将与标准输出合并，因此两者均可使用 Process.getInputStream() 方法读取。这使得关联错误消息和相应的输出变得更容易。初始值为 false 。

参数：

redirectErrorStream - 新的属性值

返回：

此进程生成器

---

start

public Process start()
              throws IOException

使用此进程生成器的属性启动一个新进程。

在 directory() 指定的工作目录中，利用 environment() 指定的进程环境，新进程将调用由 command() 给出的命令和参数。

此方法检查命令是否为一条有效的操作系统命令。哪条命令是有效的呢？这取决于系统，但至少命令必须是非空字符串的非空列表。

如果有安全管理器，则用此对象的 command 数组的首个元素作为其参数来调用安全管理器的 checkExec 方法。这可能导致抛出 SecurityException 。

启动操作系统进程的方式完全取决于系统。其中有很多方面会导致错误：

• 未找到操作系统程序文件。
• 对程序文件的访问被拒绝。
• 工作目录不存在。

在这些情况中将会抛出一个异常。该异常的具体本质取决于系统，但它总是 IOException 的一个子类。

针对此进程生成器的后续修改将不会影响返回的 Process 。

返回：

一个新的 Process 对象，用于管理子进程

抛出：

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

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

SecurityException - 如果安全管理器存在并且其 checkExec 方法不允许创建子进程

IOException - 如果发生 I/O 错误

另请参见：

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