鸿蒙OS ProcessBuilder
ProcessBuilder
java.lang.Object
|---java.lang.ProcessBuilder
public final class ProcessBuilder
extends Object此类用于创建操作系统进程。
每个 ProcessBuilder 实例管理一个流程属性的集合。 start() 方法使用这些属性创建一个新的 Process 实例。 可以从同一个实例重复调用 start() 方法来创建具有相同或相关属性的新子流程。
每个流程构建器都管理这些流程属性：
- 一个命令，一个字符串列表，表示要调用的外部程序文件及其参数（如果有）。 哪些字符串列表代表有效的操作系统命令取决于系统。 例如，每个概念参数通常是该列表中的一个元素，但在某些操作系统中，程序需要自己标记命令行字符串——在这样的系统上，Java 实现可能需要命令恰好包含两个元素。
- 环境，它是从变量到值的系统相关映射。 初始值是当前进程环境的副本。
- 一个工作目录。 默认值为当前进程的当前工作目录，通常是系统属性user.dir命名的目录。
- 标准输入源 默认情况下，子进程从管道读取输入。 Java 代码可以通过 Process#getOutputStream() 返回的输出流访问此管道。 但是，标准输入可以使用redirectInput 重定向到另一个源。 在这种情况下，Process#getOutputStream() 将返回一个空输出流，其中：
- OutputStream#write(int) 方法总是抛出 IOException
- OutputStream#close() 方法什么也不做
- 标准输出和标准错误的目的地。 默认情况下，子进程将标准输出和标准错误写入管道。 Java 代码可以通过 Process#getInputStream() 和 Process#getErrorStream() 返回的输入流访问这些管道。 但是，标准输出和标准错误可以使用redirectOutput 和redirectError 重定向到其他目的地。 在这种情况下， Process#getInputStream() 和/或 Process#getErrorStream() 将返回一个空输入流，其中：
- InputStream#read() 方法总是返回 -1
- InputStream#available() 方法总是返回 0
- InputStream#close() 方法什么也不做
- 一个 redirectErrorStream 属性。 最初，此属性为 false，这意味着子进程的标准输出和错误输出被发送到两个单独的流，可以使用 Process#getInputStream() 和 Process#getErrorStream() 方法访问它们。
如果该值设置为 true，则：
- 标准错误与标准输出合并并始终发送到相同的目的地（这使得将错误消息与相应的输出关联起来更容易）
- 标准错误和标准输出的共同目的地可以使用redirectOutput重定向
- 在创建子进程时，任何由 redirectError 方法设置的重定向都会被忽略
- 从 Process#getErrorStream() 返回的流将始终为空输入流
修改进程构建器的属性将影响随后由该对象的 start() 方法启动的进程，但不会影响先前启动的进程或 Java 进程本身。
大多数错误检查由 start() 方法执行。 可以修改对象的状态以使 start() 失败。 例如，将 command 属性设置为空列表不会引发异常，除非调用 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"));
File log = new File("log");
pb.redirectErrorStream(true);
pb.redirectOutput(Redirect.appendTo(log));
Process p = pb.start();
assert pb.redirectInput() == Redirect.PIPE;
assert pb.redirectOutput().file() == log;
assert p.getInputStream().read() == -1;要使用一组显式环境变量启动进程，请在添加环境变量之前首先调用 Map.clear()。
嵌套类摘要
| 修饰符和类型 | 类 | 描述 |
|---|---|---|
| static class | ProcessBuilder.Redirect | 表示子流程输入的来源或子流程输出的目的地。 |
构造函数摘要
| 构造函数 | 描述 |
|---|---|
| ProcessBuilder(String... command) | 使用指定的操作系统程序和参数构造一个进程构建器。 |
| ProcessBuilder(ListString command) | 使用指定的操作系统程序和参数构造一个进程构建器。 |
方法总结
| 修饰符和类型 | 方法 | 描述 |
|---|---|---|
| ListString | command() | 返回此进程构建器的操作系统程序和参数。 |
| ProcessBuilder | command(String... command) | 设置此进程构建器的操作系统程序和参数。 |
| ProcessBuilder | command(ListString command) | 设置此进程构建器的操作系统程序和参数。 |
| File | directory() | 返回此流程构建器的工作目录。 |
| ProcessBuilder | directory(File directory) | 设置此流程构建器的工作目录。 |
| MapString,String | environment() | 返回此流程构建器环境的字符串映射视图。 |
| ProcessBuilder | inheritIO() | 将子进程标准 I/O 的源和目标设置为与当前 Java 进程的相同。 |
| ProcessBuilder.Redirect | redirectError() | 返回此流程构建器的标准错误目标。 |
| ProcessBuilder | redirectError(File file) | 将此流程构建器的标准错误目标设置为文件。 |
| ProcessBuilder | redirectError(ProcessBuilder.Redirect destination) | 设置此流程构建器的标准错误目标。 |
| boolean | redirectErrorStream() | 告知此流程构建器是否合并标准错误和标准输出。 |
| ProcessBuilder | redirectErrorStream(boolean redirectErrorStream) | 设置此流程构建器的 redirectErrorStream 属性。 |
| ProcessBuilder.Redirect | redirectInput() | 返回此流程构建器的标准输入源。 |
| ProcessBuilder | redirectInput(File file) | 将此流程构建器的标准输入源设置为文件。 |
| ProcessBuilder | redirectInput(ProcessBuilder.Redirect source) | 设置此流程构建器的标准输入源。 |
| ProcessBuilder.Redirect | redirectOutput() | 返回此流程构建器的标准输出目标。 |
| ProcessBuilder | redirectOutput(File file) | 将此流程构建器的标准输出目标设置为文件。 |
| ProcessBuilder | redirectOutput(ProcessBuilder.Redirect destination) | 设置此流程构建器的标准输出目标。 |
| Process | start() | 使用此流程构建器的属性启动一个新流程。 |
| 从类 java.lang.Object 继承的方法 |
|---|
| clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
构造函数详细信息
ProcessBuilder
public ProcessBuilder(ListString command)
使用指定的操作系统程序和参数构造一个进程构建器。 此构造函数不会复制命令列表。 列表的后续更新将反映在流程构建器的状态中。 不检查命令是否对应于有效的操作系统命令。
参数：
| 参数名称 | 参数描述 |
|---|---|
| command | 包含程序及其参数的列表 |
Throws:
| Throw名称 | Throw描述 |
|---|---|
| NullPointerException | 如果参数为空 |
ProcessBuilder
public ProcessBuilder(String... command)
使用指定的操作系统程序和参数构造一个进程构建器。 这是一个方便的构造函数，它将进程构建器的命令设置为一个字符串列表，其中包含与命令数组相同的字符串，顺序相同。 不检查命令是否对应于有效的操作系统命令。
参数：
| 参数名称 | 参数描述 |
|---|---|
| command | 包含程序及其参数的字符串数组 |
方法详情
command
public ProcessBuilder command(ListString command)
设置此进程构建器的操作系统程序和参数。 此方法不会复制命令列表。 列表的后续更新将反映在流程构建器的状态中。 不检查命令是否对应于有效的操作系统命令。
参数：
| 参数名称 | 参数描述 |
|---|---|
| command | 包含程序及其参数的列表 |
返回:
此流程构建器
Throws:
| Throw名称 | Throw描述 |
|---|---|
| NullPointerException | 如果参数为空 |
command
public ProcessBuilder command(String... command)
设置此进程构建器的操作系统程序和参数。 这是一种方便的方法，它将命令设置为一个字符串列表，其中包含与命令数组相同的字符串，顺序相同。 不检查命令是否对应于有效的操作系统命令。
参数：
| 参数名称 | 参数描述 |
|---|---|
| command | 包含程序及其参数的字符串数组 |
返回:
此流程构建器
command
public ListString command()
返回此进程构建器的操作系统程序和参数。 返回的列表不是副本。 列表的后续更新将反映在此流程构建器的状态中。
返回:
此流程构建器的程序及其参数
environment
public MapString,String environment()
返回此流程构建器环境的字符串映射视图。每当创建流程构建器时，都会将环境初始化为当前流程环境的副本（请参阅 System#getenv()）。随后由该对象的 start() 方法启动的子进程将使用该映射作为它们的环境。
返回的对象可以使用普通的 Map 操作进行修改。这些修改将对通过 start() 方法启动的子进程可见。两个 ProcessBuilder 实例始终包含独立的流程环境，因此对返回映射的更改将永远不会反映在任何其他 ProcessBuilder 实例或 System#getenv 返回的值中。
如果系统不支持环境变量，则返回一个空映射。
返回的映射不允许空键或值。尝试插入或查询是否存在空键或值将引发 NullPointerException。尝试查询是否存在非 String 类型的键或值将引发 ClassCastException。
返回地图的行为取决于系统。系统可能不允许修改环境变量或可能禁止某些变量名称或值。因此，如果操作系统不允许修改，尝试修改映射可能会失败并出现 UnsupportedOperationException 或 IllegalArgumentException。
由于环境变量名称和值的外部格式取决于系统，因此它们与 Java 的 Unicode 字符串之间可能没有一对一的映射。尽管如此，映射的实现方式是，未由 Java 代码修改的环境变量将在子进程中具有未修改的本机表示。
返回的地图及其集合视图可能不遵守 Object#equals 和 Object#hashCode 方法的一般约定。
返回的地图通常在所有平台上都区分大小写。
如果存在安全管理器，则使用 RuntimePermission("getenv.*") 权限调用其 SecurityManager#checkPermission 方法。这可能会导致抛出 SecurityException。
将信息传递给 Java 子进程时，系统属性通常优于环境变量。
返回：
此流程构建器的环境
Throws:
| Throw名称 | Throw描述 |
|---|---|
| SecurityException | 如果存在安全管理器并且其 SecurityManager#checkPermission 方法不允许访问进程环境 |
directory
public File directory()
返回此流程构建器的工作目录。 随后由该对象的 start() 方法启动的子进程将使用它作为其工作目录。 返回值可能为null——表示使用当前Java进程的工作目录，通常是系统属性user.dir命名的目录，作为子进程的工作目录。
返回:
此流程构建器的工作目录
directory
public ProcessBuilder directory(File directory)
设置此流程构建器的工作目录。 随后由该对象的 start() 方法启动的子进程将使用它作为其工作目录。 参数可以为null——表示使用当前Java进程的工作目录，通常是系统属性user.dir命名的目录，作为子进程的工作目录。
参数：
| 参数名称 | 参数描述 |
|---|---|
| directory | 新的工作目录 |
返回:
此流程构建器
redirectInput
public ProcessBuilder redirectInput(ProcessBuilder.Redirect source)
设置此流程构建器的标准输入源。 随后由该对象的 start() 方法启动的子进程从此源获取其标准输入。
如果源是 Redirect#PIPE（初始值），则可以使用 Process#getOutputStream() 返回的输出流写入子进程的标准输入。 如果源设置为任何其他值，则 Process#getOutputStream() 将返回一个空输出流。
参数：
| 参数名称 | 参数描述 |
|---|---|
| source | 新的标准输入源 |
返回:
此流程构建器
Throws:
| Throw名称 | Throw描述 |
|---|---|
| IllegalArgumentException | 如果重定向不对应于有效的数据源，即类型为 WRITE 或 APPEND |
redirectOutput
public ProcessBuilder redirectOutput(ProcessBuilder.Redirect destination)
设置此流程构建器的标准输出目标。 随后由该对象的 start() 方法启动的子进程将其标准输出发送到该目的地。
如果目标是 Redirect#PIPE（初始值），则可以使用 Process#getInputStream() 返回的输入流读取子进程的标准输出。 如果目标设置为任何其他值，则 Process#getInputStream() 将返回一个空输入流。
参数：
| 参数名称 | 参数描述 |
|---|---|
| destination | 新的标准输出目的地 |
返回:
此流程构建器
Throws:
| Throw名称 | Throw描述 |
|---|---|
| IllegalArgumentException | 如果重定向不对应于数据的有效目的地，即类型为 READ |
redirectError
public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)
设置此流程构建器的标准错误目标。 随后由该对象的 start() 方法启动的子进程将其标准错误发送到该目的地。
如果目标是 Redirect#PIPE（初始值），则可以使用 Process#getErrorStream() 返回的输入流读取子进程的错误输出。 如果目标设置为任何其他值，则 Process#getErrorStream() 将返回空输入流。
如果redirectErrorStream 属性已设置为true，则此方法设置的重定向无效。
参数：
| 参数名称 | 参数描述 |
|---|---|
| destination | 新的标准错误目的地 |
返回:
此流程构建器
Throws:
| Throw名称 | Throw描述 |
|---|---|
| IllegalArgumentException | 如果重定向不对应于数据的有效目的地，即类型为 READ |
redirectInput
public ProcessBuilder redirectInput(File file)
将此流程构建器的标准输入源设置为文件。
这是一种方便的方法。 形式redirectInput(file) 的调用与调用redirectInput (Redirect.from(file)) 的行为方式完全相同。
参数：
| 参数名称 | 参数描述 |
|---|---|
| file | 新的标准输入源 |
返回:
此流程构建器
redirectOutput
public ProcessBuilder redirectOutput(File file)
将此流程构建器的标准输出目标设置为文件。
这是一种方便的方法。 形式redirectOutput(file) 的调用与调用redirectOutput (Redirect.to(file)) 的行为方式完全相同。
参数：
| 参数名称 | 参数描述 |
|---|---|
| file | 新的标准输出目的地 |
返回:
此流程构建器
redirectError
public ProcessBuilder redirectError(File file)
将此流程构建器的标准错误目标设置为文件。
这是一种方便的方法。 调用redirectError(file) 形式的行为与调用redirectError (Redirect.to(file)) 完全相同。
参数：
| 参数名称 | 参数描述 |
|---|---|
| file | 新的标准错误目的地 |
返回:
此流程构建器
redirectInput
public ProcessBuilder.Redirect redirectInput()
返回此流程构建器的标准输入源。 随后由该对象的 start() 方法启动的子进程从此源获取其标准输入。 初始值为重定向#PIPE。
返回:
此流程构建器的标准输入源
redirectOutput
public ProcessBuilder.Redirect redirectOutput()
返回此流程构建器的标准输出目标。 随后由该对象的 start() 方法启动的子进程将其标准输出重定向到该目的地。 初始值为重定向#PIPE。
返回:
此流程构建器的标准输出目的地
redirectError
public ProcessBuilder.Redirect redirectError()
返回此流程构建器的标准错误目标。 随后由该对象的 start() 方法启动的子进程将其标准错误重定向到该目的地。 初始值为重定向#PIPE。
返回:
此流程构建器的标准错误目的地
inheritIO
public ProcessBuilder inheritIO()
将子进程标准 I/O 的源和目标设置为与当前 Java 进程的相同。
这是一种方便的方法。 表单的调用
pb.inheritIO() 行为方式与调用完全相同
pb.redirectInput(Redirect.INHERIT) .redirectOutput(Redirect.INHERIT) .redirectError(Redirect.INHERIT) 这提供了相当于大多数操作系统命令解释器或标准 C 库函数 system() 的行为。
返回:
此流程构建器
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() 给出的工作目录中调用由 command() 给出的命令和参数，以及由 environment() 给出的进程环境。
此方法检查该命令是否为有效的操作系统命令。哪些命令有效取决于系统，但至少该命令必须是非空字符串的非空列表。
在某些操作系统上启动进程可能需要一组最小的系统相关环境变量。因此，子流程可能会继承流程构建器的 environment() 之外的其他环境变量设置。
如果存在安全管理器，则调用其 SecurityManager#checkExec 方法，并使用此对象的命令数组的第一个组件作为其参数。这可能会导致抛出 SecurityException。
启动操作系统进程高度依赖于系统。可能出错的许多事情包括：
- 未找到操作系统程序文件。
- 访问程序文件被拒绝。
- 工作目录不存在。
在这种情况下会抛出异常。 异常的确切性质取决于系统，但它始终是 IOException 的子类。
对此流程构建器的后续修改不会影响返回的流程。
返回:
用于管理子流程的新流程对象
Throws:
| Throw名称 | Throw描述 |
|---|---|
| NullPointerException | 如果命令列表的元素为空 |
| IndexOutOfBoundsException | 如果命令是一个空列表（大小为 0） |
| SecurityException | 如果存在安全管理器并且其 SecurityManager#checkExec 方法不允许创建子进程，或者子进程的标准输入从文件重定向并且安全管理器的 SecurityManager#checkRead 方法拒绝读取文件，或者标准输出或标准 子进程的错误被重定向到文件并且安全管理器的 SecurityManager#checkWrite 方法拒绝对文件的写访问 |
| IOException | 如果发生 I/O 错误 |