鸿蒙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()。

嵌套类摘要

构造函数摘要

方法总结

构造函数详细信息

ProcessBuilder

public ProcessBuilder(ListString command)

使用指定的操作系统程序和参数构造一个进程构建器。 此构造函数不会复制命令列表。 列表的后续更新将反映在流程构建器的状态中。 不检查命令是否对应于有效的操作系统命令。

参数：

Throws:

ProcessBuilder

public ProcessBuilder(String… command)

使用指定的操作系统程序和参数构造一个进程构建器。 这是一个方便的构造函数，它将进程构建器的命令设置为一个字符串列表，其中包含与命令数组相同的字符串，顺序相同。 不检查命令是否对应于有效的操作系统命令。

参数：

方法详情

command

public ProcessBuilder command(ListString command)

设置此进程构建器的操作系统程序和参数。 此方法不会复制命令列表。 列表的后续更新将反映在流程构建器的状态中。 不检查命令是否对应于有效的操作系统命令。

参数：

返回:

此流程构建器

Throws:

command

public ProcessBuilder command(String… 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:

directory

public File directory()

返回此流程构建器的工作目录。 随后由该对象的 start() 方法启动的子进程将使用它作为其工作目录。 返回值可能为null——表示使用当前Java进程的工作目录，通常是系统属性user.dir命名的目录，作为子进程的工作目录。

返回:

此流程构建器的工作目录

directory

public ProcessBuilder directory(File directory)

设置此流程构建器的工作目录。 随后由该对象的 start() 方法启动的子进程将使用它作为其工作目录。 参数可以为null——表示使用当前Java进程的工作目录，通常是系统属性user.dir命名的目录，作为子进程的工作目录。

参数：

返回:

此流程构建器

redirectInput

public ProcessBuilder redirectInput(ProcessBuilder.Redirect source)

设置此流程构建器的标准输入源。 随后由该对象的 start() 方法启动的子进程从此源获取其标准输入。

如果源是 Redirect#PIPE（初始值），则可以使用 Process#getOutputStream() 返回的输出流写入子进程的标准输入。 如果源设置为任何其他值，则 Process#getOutputStream() 将返回一个空输出流。

参数：

返回:

此流程构建器

Throws:

redirectOutput

public ProcessBuilder redirectOutput(ProcessBuilder.Redirect destination)

设置此流程构建器的标准输出目标。 随后由该对象的 start() 方法启动的子进程将其标准输出发送到该目的地。

如果目标是 Redirect#PIPE（初始值），则可以使用 Process#getInputStream() 返回的输入流读取子进程的标准输出。 如果目标设置为任何其他值，则 Process#getInputStream() 将返回一个空输入流。

参数：

返回:

此流程构建器

Throws:

redirectError

public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)

设置此流程构建器的标准错误目标。 随后由该对象的 start() 方法启动的子进程将其标准错误发送到该目的地。

如果目标是 Redirect#PIPE（初始值），则可以使用 Process#getErrorStream() 返回的输入流读取子进程的错误输出。 如果目标设置为任何其他值，则 Process#getErrorStream() 将返回空输入流。

如果redirectErrorStream 属性已设置为true，则此方法设置的重定向无效。

参数：

返回:

此流程构建器

Throws:

redirectInput

public ProcessBuilder redirectInput(File file)

将此流程构建器的标准输入源设置为文件。

这是一种方便的方法。 形式redirectInput(file) 的调用与调用redirectInput (Redirect.from(file)) 的行为方式完全相同。

参数：

返回:

此流程构建器

redirectOutput

public ProcessBuilder redirectOutput(File file)

将此流程构建器的标准输出目标设置为文件。

这是一种方便的方法。 形式redirectOutput(file) 的调用与调用redirectOutput (Redirect.to(file)) 的行为方式完全相同。

参数：

返回:

此流程构建器

redirectError

public ProcessBuilder redirectError(File file)

将此流程构建器的标准错误目标设置为文件。

这是一种方便的方法。 调用redirectError(file) 形式的行为与调用redirectError (Redirect.to(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。

参数：

返回:

此流程构建器

start

public Process start() throws IOException

使用此流程构建器的属性启动一个新流程。

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

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

在某些操作系统上启动进程可能需要一组最小的系统相关环境变量。因此，子流程可能会继承流程构建器的 environment() 之外的其他环境变量设置。

如果存在安全管理器，则调用其 SecurityManager#checkExec 方法，并使用此对象的命令数组的第一个组件作为其参数。这可能会导致抛出 SecurityException。

启动操作系统进程高度依赖于系统。可能出错的许多事情包括：

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

在这种情况下会抛出异常。 异常的确切性质取决于系统，但它始终是 IOException 的子类。

对此流程构建器的后续修改不会影响返回的流程。

返回:

用于管理子流程的新流程对象

Throws: