模块  java.base
软件包  java.lang

Class ProcessBuilder

  • public final class ProcessBuilder
extends Object
    此类用于创建操作系统进程。

    每个ProcessBuilder实例管理一组进程属性。 start()方法使用这些属性创建新的Process实例。 可以从同一实例重复调用start()方法，以创建具有相同或相关属性的新子进程 。

    可以调用startPipeline方法来创建新进程的管道，将每个进程的输出直接发送到下一个进程。 每个进程都具有其各自ProcessBuilder的属性。

    每个流程构建器都管理这些流程属性

    • 一个命令 ，一个字符串列表，表示要调用的外部程序文件及其参数（如果有）。 哪个字符串列表表示有效的操作系统命令取决于系统。 例如，每个概念参数通常都是此列表中的元素，但是有些操作系统需要程序对命令行字符串本身进行标记 - 在这样的系统上，Java实现可能需要命令才能包含两个元素。
    • 环境 ，是从变量到值的系统相关映射。 初始值是当前进程的环境副本（请参阅System.getenv() ）。
    • 一个工作目录 。 默认值是当前进程的当前工作目录，通常是系统属性user.dir指定的目录。
    • a source of standard input 。 默认情况下，子进程从管道读取输入。 Java代码可以通过Process.getOutputStream()返回的输出流访问此管道。 但是，可以使用redirectInput将标准输入重定向到另一个源。 在这种情况下， Process.getOutputStream()将返回一个空输出流 ，其中：
      • write方法总是抛出IOException
      • close方法什么都不做
    • a destination for standard output and standard error 。 默认情况下，子进程将标准输出和标准错误写入管道。 Java代码可以通过Process.getOutputStream()和Process.getErrorStream()返回的输入流访问这些管道。 但是，可以使用redirectOutput和redirectError将标准输出和标准错误重定向到其他目标。 在这种情况下， Process.getInputStream()和/或Process.getErrorStream()将返回空输入流 ，其中：
    • redirectErrorStream属性。 最初，此属性为false ，这意味着子false的标准输出和错误输出将发送到两个单独的流，可以使用Process.getInputStream()和Process.getErrorStream()方法访问这些流。

      如果该值设置为true ，则：

    修改流程构建器的属性将影响随后由该对象的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")); 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() 。

    除非另有说明，否则将null参数传递给null中的构造函数或方法将导致抛出NullPointerException 。

    从以下版本开始：
    1.5

    • 构造方法详细信息

      • ProcessBuilder

        public ProcessBuilder​(List<String> command)
        使用指定的操作系统程序和参数构造流程构建器。 此构造不会使副本command名单。 对列表的后续更新将反映在流程构建器的状态中。 不检查command是否对应于有效的操作系统命令。
        参数
        command - 包含程序及其参数的列表

      • ProcessBuilder

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

    • 方法详细信息

      • command

        public ProcessBuilder command​(List<String> command)
        设置此进程生成器的操作系统程序和参数。 这种方法不会使副本command名单。 对列表的后续更新将反映在流程构建器的状态中。 不检查command是否对应于有效的操作系统命令。
        参数
        command - 包含程序及其参数的列表
        结果
        这个流程构建器

      • 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()方法的一般合同。

        返回的映射通常在所有平台上都区分大小写。

        如果存在安全管理器，则使用RuntimePermission ("getenv.*")权限调用其checkPermission方法。 这可能会导致抛出SecurityException 。

        将信息传递给Java子进程时 ， system properties通常优先于环境变量。

        结果
        这个流程构建器的环境
        异常
        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 - 新的工作目录
        结果
        这个流程构建器

      • redirectInput

        public ProcessBuilder redirectInput​(File file)
        将此流程构建器的标准输入源设置为文件。

        这是一种方便的方法。 调用窗体redirectInput(file)行为与调用redirectInput (Redirect.from(file)) 。

        参数
        file - 新的标准输入源
        结果
        这个流程构建器
        从以下版本开始：
        1.7

      • redirectOutput

        public ProcessBuilder redirectOutput​(File file)
        将此流程构建器的标准输出目标设置为文件。

        这是一种方便的方法。 调用redirectOutput(file)表单的行为与调用redirectOutput (Redirect.to(file)) 。

        参数
        file - 新的标准输出目标
        结果
        这个流程构建器
        从以下版本开始：
        1.7

      • redirectError

        public ProcessBuilder redirectError​(File file)
        将此流程构建器的标准错误目标设置为文件。

        这是一种方便的方法。 调用窗体redirectError(file)行为与调用redirectError (Redirect.to(file)) 。

        参数
        file - 新的标准错误目标
        结果
        这个流程构建器
        从以下版本开始：
        1.7

      • redirectInput

        public ProcessBuilder.Redirect redirectInput()
        返回此流程构建器的标准输入源。 随后由此对象的start()方法启动的子进程从此源获取其标准输入。 初始值为Redirect.PIPE 。
        结果
        此流程构建器的标准输入源
        从以下版本开始：
        1.7

      • redirectOutput

        public ProcessBuilder.Redirect redirectOutput()
        返回此流程构建器的标准输出目标。 随后由此对象的start()方法启动的子进程将其标准输出重定向到此目标。 初始值为Redirect.PIPE 。
        结果
        此流程构建器的标准输出目标
        从以下版本开始：
        1.7

      • redirectError

        public ProcessBuilder.Redirect redirectError()
        返回此流程构建器的标准错误目标。 随后由此对象的start()方法启动的子进程将其标准错误重定向到此目标。 初始值为Redirect.PIPE 。
        结果
        此进程构建器的标准错误目标
        从以下版本开始：
        1.7

      • inheritIO

        public ProcessBuilder inheritIO()
        将子进程标准I / O的源和目标设置为与当前Java进程的源和目标相同。

        这是一种方便的方法。 调用表单 

           pb.inheritIO()
        行为与调用完全相同 
           pb.redirectInput(Redirect.INHERIT) .redirectOutput(Redirect.INHERIT) .redirectError(Redirect.INHERIT)
        这提供了与大多数操作系统命令解释程序或标准C库函数system() 。
        结果
        这个流程构建器
        从以下版本开始：
        1.7

      • redirectErrorStream

        public boolean redirectErrorStream()
        判断此流程构建器是否合并标准错误和标准输出。

        如果此属性为true ，则此对象的start()方法随后启动的子true生成的任何错误输出都将与标准输出合并，以便可以使用Process.getInputStream()方法读取这两个错误 。 这样可以更容易地将错误消息与相应的输出相关联。 初始值为false 。

        结果
        此流程构建器的 redirectErrorStream属性

      • redirectErrorStream

        public ProcessBuilder redirectErrorStream​(boolean redirectErrorStream)
        设置此进程生成器的redirectErrorStream属性。

        如果此属性为true ，则此对象的start()方法随后启动的子true生成的任何错误输出都将与标准输出合并，以便可以使用Process.getInputStream()方法读取这两个错误 。 这样可以更容易地将错误消息与相应的输出相关联。 初始值为false 。

        参数
        redirectErrorStream - 新属性值
        结果
        这个流程构建器

      • start

        public Process start()
              throws IOException
        使用此流程构建器的属性启动新流程。

        新进程将调用由指定的命令和参数command()按以下给出，在工作目录directory() ，有一个过程的环境被给出environment() 。

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

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

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

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

        • 找不到操作系统程序文件。
        • 访问程序文件被拒绝。
        • 工作目录不存在。
        • 命令参数中的字符无效，例如NUL。

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

        如果操作系统不支持创建进程，则将抛出UnsupportedOperationException 。

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

        结果
        用于管理子进程的新对象Process
        异常
        NullPointerException - 如果命令列表的元素为null
        IndexOutOfBoundsException - 如果该命令是空列表（大小为 0 ）
        SecurityException - 如果存在安全管理器并且
        UnsupportedOperationException - 如果操作系统不支持创建进程。
        IOException - 如果发生I / O错误
        另请参见：
        Runtime.exec(String[], String[], java.io.File)

      • startPipeline

        public static List<Process> startPipeline​(List<ProcessBuilder> builders)
                                   throws IOException
        为每个ProcessBuilder启动一个Process，创建一个由标准输出和标准输入流链接的流程管道。 每个ProcessBuilder的属性用于启动相应的进程，除了每个进程启动时，其标准输出将定向到下一个进程的标准输入。 使用相应ProcessBuilder的重定向设置初始化第一个进程的标准输入和最后一个进程的标准输出的重定向。 所有其他ProcessBuilder重定向应为Redirect.PIPE 。

        无法访问中间进程之间的所有输入和输出流。 除第一个进程外的所有进程的standard input都是空输出流除了最后一个进程之外的所有进程的standard output都是空输入流 。

        每个ProcessBuilder的redirectErrorStream()适用于相应的流程。 如果设置为true ，则错误流将写入与标准输出相同的流。

        如果启动任何进程抛出异常，则强制销毁所有进程。

        该startPipeline方法一样的每个的ProcessBuilder执行相同的检查start()方法。 新进程将调用由指定的命令和参数command()按以下给出，在工作目录directory() ，有一个过程的环境被给出environment() 。

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

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

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

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

        • 找不到操作系统程序文件。
        • 访问程序文件被拒绝。
        • 工作目录不存在。
        • 命令参数中的字符无效，例如NUL。

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

        如果操作系统不支持创建进程，则会抛出UnsupportedOperationException 。

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

        API Note:
        例如，要计算Unix兼容平台上文件层次结构中所有文件的唯一导入： 
           String directory = "/home/duke/src"; ProcessBuilder[] builders = { new ProcessBuilder("find", directory, "-type", "f"), new ProcessBuilder("xargs", "grep", "-h", "^import "), new ProcessBuilder("awk", "{print $2;}"), new ProcessBuilder("sort", "-u")}; List<Process> processes = ProcessBuilder.startPipeline( Arrays.asList(builders)); Process last = processes.get(processes.size()-1); try (InputStream is = last.getInputStream(); Reader isr = new InputStreamReader(is); BufferedReader r = new BufferedReader(isr)) { long count = r.lines().count(); }
        参数
        builders - ProcessBuilders列表
        结果
        a List<Process> es从相应的ProcessBuilder开始
        异常
        IllegalArgumentException - 除第一个构建器的标准输入和最后一个构建器的标准输出之外的任何重定向都不是 ProcessBuilder.Redirect.PIPE 。
        NullPointerException - 如果命令列表的元素为null或者ProcessBuilder列表的元素为null或者builders参数为null
        IndexOutOfBoundsException - 如果该命令是空列表（大小为 0 ）
        SecurityException - 如果存在安全管理器并且
        UnsupportedOperationException - 如果操作系统不支持创建进程
        IOException - 如果发生I / O错误
        从以下版本开始：
        9