Класс ProcessBuilder

java.lang.Object

java.lang.ProcessBuilder

public final class ProcessBuilder extends Object

Этот класс используется для создания процессов операционной системы.

Каждый экземпляр ProcessBuilder управляет набором атрибутов процесса. Метод start() создает новый экземпляр Process с этими атрибутами. Метод start() можно вызывать многократно для одного и того же экземпляра, чтобы создавать новые подпроцессы с идентичными или связанными атрибутами.

Метод startPipeline можно вызвать для создания конвейера новых процессов, в котором каждый процесс напрямую передает выходные данные следующему процессу. Каждый процесс имеет атрибуты соответствующего ProcessBuilder.

Каждый построитель процессов управляет следующими атрибутами процесса:

командой — списком строк, задающим файл внешней программы для запуска и ее аргументы, если они есть. Какие списки строк представляют допустимую команду операционной системы, зависит от системы. Например, часто каждый логический аргумент является отдельным элементом этого списка, однако существуют операционные системы, в которых программы должны самостоятельно разбивать строки командной строки на токены — в такой системе реализация Java может требовать, чтобы команды содержали ровно два элемента.
окружением — зависящим от системы отображением переменных в значения. Начальным значением является копия окружения текущего процесса (см. System.getenv()).
рабочим каталогом. Значением по умолчанию является текущий рабочий каталог текущего процесса, обычно каталог, указанный системным свойством user.dir.
источником стандартного ввода. По умолчанию подпроцесс считывает входные данные из канала. Код Java может обращаться к этому каналу через выходной поток, возвращаемый методом Process.getOutputStream(). Однако стандартный ввод можно перенаправить из другого источника с помощью метода redirectInput. В этом случае метод Process.getOutputStream() вернет пустой выходной поток, для которого:
- методы write всегда выбрасывают IOException
- метод close ничего не делает
назначением для стандартного вывода и стандартного потока ошибок. По умолчанию подпроцесс записывает стандартный вывод и стандартный поток ошибок в каналы. Код Java может обращаться к этим каналам через входные потоки, возвращаемые методами Process.getInputStream() и Process.getErrorStream(). Однако стандартный вывод и стандартный поток ошибок можно перенаправить в другие места назначения с помощью методов redirectOutput и redirectError. В этом случае методы Process.getInputStream() и/или Process.getErrorStream() вернут пустой входной поток, для которого:
- методы read всегда возвращают -1
- метод available всегда возвращает 0
- метод close ничего не делает
свойством redirectErrorStream. Изначально это свойство имеет значение false, означающее, что стандартный вывод и поток ошибок подпроцесса передаются в два отдельных потока, к которым можно обращаться с помощью методов Process.getInputStream() и Process.getErrorStream().
Если для этого свойства задано значение true, то:
- стандартный поток ошибок объединяется со стандартным выводом и всегда передается в одно и то же место назначения (это упрощает сопоставление сообщений об ошибках с соответствующими выходными данными)
- общее место назначения стандартного потока ошибок и стандартного вывода можно перенаправить с помощью метода redirectOutput
- любое перенаправление, заданное методом redirectError, игнорируется при создании подпроцесса
- поток, возвращаемый методом 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"));
    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 конструктору или методу этого класса приведет к выбрасыванию NullPointerException.

С версии:: 1.5

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static class`	`ProcessBuilder.Redirect`	Представляет источник ввода подпроцесса или место назначения вывода подпроцесса.

Краткое описание конструкторов

Конструктор	Описание
`ProcessBuilder(String... command)`	Создает построитель процессов с указанной программой операционной системы и аргументами.
`ProcessBuilder(List<String> command)`	Создает построитель процессов с указанной программой операционной системы и аргументами.

Краткое описание методов

Модификатор и тип	Метод	Описание
`List<String>`	`command()`	Возвращает программу операционной системы и аргументы этого построителя процессов.
`ProcessBuilder`	`command(String... command)`	Задает программу операционной системы и аргументы этого построителя процессов.
`ProcessBuilder`	`command(List<String> command)`	Задает программу операционной системы и аргументы этого построителя процессов.
`File`	`directory()`	Возвращает рабочий каталог этого построителя процессов.
`ProcessBuilder`	`directory(File directory)`	Задает рабочий каталог этого построителя процессов.
`Map<String,String>`	`environment()`	Возвращает представление окружения этого построителя процессов в виде карты строк.
`ProcessBuilder`	`inheritIO()`	Задает для стандартного ввода-вывода подпроцесса те же источники и места назначения, что и для текущего процесса 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()`	Запускает новый процесс с атрибутами этого построителя процессов.
`static List<Process>`	`startPipeline(List<ProcessBuilder> builders)`	Запускает процесс для каждого ProcessBuilder, создавая конвейер процессов, связанных потоками стандартного вывода и стандартного ввода.

Методы, объявленные в классе Object

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

Подробное описание конструкторов

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.

Если система не поддерживает переменные среды, возвращается пустая карта.

Возвращенная карта не допускает ключи и значения null. Попытка вставить ключ или значение null либо проверить их наличие приведет к возникновению исключения NullPointerException. Попытка проверить наличие ключа или значения, не принадлежащего типу String, приведет к возникновению исключения ClassCastException.

Поведение возвращенной карты зависит от системы. Система может не разрешать изменение переменных среды или запрещать определенные имена либо значения переменных. Поэтому попытки изменить карту могут завершиться исключением UnsupportedOperationException или IllegalArgumentException, если изменение не разрешено операционной системой.

Поскольку внешний формат имен и значений переменных среды зависит от системы, взаимно однозначное соответствие между ними и строками Unicode в Java может отсутствовать. Тем не менее карта реализована таким образом, что переменные среды, не измененные кодом Java, будут иметь в дочернем процессе неизмененное исходное представление.

Возвращенная карта и ее представления коллекций могут не соответствовать общему контракту методов Object.equals(Object) и Object.hashCode().

На большинстве платформ возвращенная карта обычно чувствительна к регистру.

При передаче данных дочернему процессу Java обычно предпочтительнее использовать системные свойства, а не переменные среды.

Возвращает:

среду этого построителя процессов

См. также:

redirectInput

public ProcessBuilder redirectInput(ProcessBuilder.Redirect source)

Задает источник стандартного ввода этого построителя процессов. Впоследствии дочерние процессы, запускаемые методом start() этого объекта, будут получать стандартный ввод из этого источника.

Если источником является Redirect.PIPE (начальное значение), стандартный ввод дочернего процесса можно записывать с помощью потока вывода, возвращаемого методом Process.getOutputStream(). Если источнику задано любое другое значение, метод Process.getOutputStream() вернет пустой поток вывода.

Параметры:: source — новый источник стандартного ввода
Возвращает:: этот построитель процессов
Вызывает:: IllegalArgumentException — если перенаправление не соответствует допустимому источнику данных, то есть имеет тип WRITE или APPEND
Начиная с:: 1.7

redirectOutput

public ProcessBuilder redirectOutput(ProcessBuilder.Redirect destination)

Задает назначение стандартного вывода этого построителя процессов. Впоследствии дочерние процессы, запускаемые методом start() этого объекта, будут отправлять стандартный вывод в это назначение.

Если назначением является Redirect.PIPE (начальное значение), стандартный вывод дочернего процесса можно считывать с помощью потока ввода, возвращаемого методом Process.getInputStream(). Если назначению задано любое другое значение, метод Process.getInputStream() вернет пустой поток ввода.

Параметры:: destination — новое назначение стандартного вывода
Возвращает:: этот построитель процессов
Вызывает:: IllegalArgumentException — если перенаправление не соответствует допустимому назначению данных, то есть имеет тип READ
Начиная с:: 1.7

redirectError

public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)

Задает назначение стандартного потока ошибок этого построителя процессов. Впоследствии дочерние процессы, запускаемые методом start() этого объекта, будут отправлять стандартный поток ошибок в это назначение.

Если назначением является Redirect.PIPE (начальное значение), вывод ошибок дочернего процесса можно считывать с помощью потока ввода, возвращаемого методом Process.getErrorStream(). Если назначению задано любое другое значение, метод Process.getErrorStream() вернет пустой поток ввода.

Если атрибуту redirectErrorStream задано значение true, перенаправление, заданное этим методом, не действует.

Параметры:: destination — новое назначение стандартного потока ошибок
Возвращает:: этот построитель процессов
Вызывает:: IllegalArgumentException — если перенаправление не соответствует допустимому назначению данных, то есть имеет тип READ
Начиная с:: 1.7

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()

Задает источники и назначения стандартного ввода-вывода дочернего процесса такими же, как у текущего процесса Java.

Этот метод предоставлен для удобства. Вызов вида

     pb.inheritIO()

действует точно так же, как вызов

     pb.redirectInput(Redirect.INHERIT)
         .redirectOutput(Redirect.INHERIT)
         .redirectError(Redirect.INHERIT)

Это обеспечивает поведение, эквивалентное поведению большинства интерпретаторов команд операционной системы или стандартной функции библиотеки C system().

Возвращает:: этот построитель процессов
Начиная с:: 1.7

redirectErrorStream

public boolean redirectErrorStream()

Показывает, объединяет ли этот построитель процессов стандартный поток ошибок со стандартным выводом.

Если этому свойству присвоено значение true, весь вывод ошибок, созданный впоследствии дочерними процессами, запускаемыми методом start() этого объекта, будет объединен со стандартным выводом, так что оба потока можно будет считывать методом Process.getInputStream(). Это упрощает сопоставление сообщений об ошибках с соответствующим выводом. Начальное значение — false.

Возвращает:: значение свойства redirectErrorStream этого построителя процессов

redirectErrorStream

public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)

Задает свойство redirectErrorStream этого построителя процессов.

Параметры:: redirectErrorStream — новое значение свойства
Возвращает:: этот построитель процессов

start

public Process start() throws IOException

Запускает новый процесс с использованием атрибутов этого построителя процессов.

Новый процесс выполнит команду и аргументы, заданные методом command(), в рабочем каталоге, заданном методом directory(), и со средой процесса, заданной методом environment().

Этот метод проверяет, является ли команда допустимой командой операционной системы. Набор допустимых команд зависит от системы, но как минимум команда должна быть непустым списком строк, не содержащих null.

В некоторых операционных системах для запуска процесса может потребоваться минимальный набор системно-зависимых переменных среды. В результате дочерний процесс может унаследовать дополнительные параметры переменных среды сверх указанных в environment() построителя процессов. Минимальный набор системно-зависимых переменных среды может переопределить значения, указанные в среде.

Запуск процесса операционной системы сильно зависит от системы. Среди множества возможных проблем:

Файл программы операционной системы не найден.
Доступ к файлу программы запрещен.
Рабочий каталог не существует.
Недопустимый символ в аргументе команды, например NUL.

В таких случаях будет выброшено исключение. Точный тип исключения зависит от системы, но оно всегда будет подклассом IOException.

Если операционная система не поддерживает создание процессов, будет выброшено исключение UnsupportedOperationException.

Последующие изменения этого построителя процессов не повлияют на возвращенный объект Process.

Примечание по реализации:

В эталонной реализации можно включить журналирование команды, аргументов, каталога, трассировки стека и идентификатора процесса. Журналируемая информация может содержать конфиденциальные сведения, связанные с безопасностью, поэтому следует тщательно оценить риск их раскрытия. Журналирование включается, если уровень журнала системного регистратора с именем java.lang.ProcessBuilder равен Level.DEBUG или Level.TRACE. При включении для Level.DEBUG журналируются только идентификатор процесса, каталог, команда и трассировка стека. При включении для Level.TRACE вместе с идентификатором процесса, каталогом, командой и трассировкой стека журналируются также аргументы.

Возвращает:

новый объект Process для управления дочерним процессом

Вызывает:

NullPointerException — если элемент списка команд равен null

IndexOutOfBoundsException — если список команд пуст (имеет размер 0)

UnsupportedOperationException — если операционная система не поддерживает создание процессов.

IOException — если возникает ошибка ввода-вывода

См. также:

startPipeline

public static List<Process> startPipeline(List<ProcessBuilder> builders) throws IOException

Запускает процесс для каждого объекта ProcessBuilder, создавая конвейер процессов, связанных потоками стандартного вывода и стандартного ввода. Для запуска соответствующего процесса используются атрибуты каждого объекта ProcessBuilder, за исключением того, что по мере запуска процессов стандартный вывод каждого процесса направляется в стандартный ввод следующего. Перенаправления стандартного ввода первого процесса и стандартного вывода последнего процесса инициализируются с использованием настроек перенаправления соответствующих объектов ProcessBuilder. Все остальные перенаправления ProcessBuilder должны иметь значение Redirect.PIPE.

Потоки ввода и вывода между промежуточными процессами недоступны. Метод standard input для всех процессов, кроме первого, возвращает пустые потоки вывода. Метод standard output для всех процессов, кроме последнего, возвращает пустые потоки ввода.

Свойство redirectErrorStream() каждого объекта ProcessBuilder применяется к соответствующему процессу. Если ему задано значение true, поток ошибок записывается в тот же поток, что и стандартный вывод.

Если при запуске любого из процессов возникает исключение, все процессы принудительно завершаются.

Метод startPipeline выполняет для каждого объекта ProcessBuilder те же проверки, что и метод start(). Каждый новый процесс выполняет команду и аргументы, заданные методом command() соответствующего построителя процессов, в рабочем каталоге, заданном его методом directory(), и со средой процесса, заданной его методом environment().

Команда каждого построителя процессов проверяется на соответствие допустимой команде операционной системы. Набор допустимых команд зависит от системы, но как минимум команда должна быть непустым списком строк, не содержащих null.

Запуск процесса операционной системы сильно зависит от системы. Среди множества возможных проблем:

Файл программы операционной системы не найден.
Доступ к файлу программы запрещен.
Рабочий каталог не существует.
Недопустимый символ в аргументе команды, например NUL.

Если операционная система не поддерживает создание процессов, будет выброшено исключение UnsupportedOperationException.

Последующие изменения любого из указанных построителей не повлияют на возвращенный объект Process.

Примечание к API:

Например, чтобы подсчитать уникальные импорты во всех файлах иерархии каталогов на платформе, совместимой с 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();
    }

Примечание по реализации:

В эталонной реализации можно включить журналирование каждого созданного процесса; подробности см. в разделе start().

Параметры:

builders — список объектов ProcessBuilder

Возвращает:

объекты List<Process>, запущенные соответствующими объектами ProcessBuilder

Вызывает:

IllegalArgumentException — любое перенаправление, кроме стандартного ввода первого построителя и стандартного вывода последнего построителя, не имеет значения ProcessBuilder.Redirect.PIPE.

NullPointerException — если элемент списка команд равен null, элемент списка ProcessBuilder равен null или аргумент builders равен null

IndexOutOfBoundsException — если список команд пуст (имеет размер 0)

UnsupportedOperationException — если операционная система не поддерживает создание процессов

IOException — если возникает ошибка ввода-вывода

Начиная с:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/ProcessBuilder.html