Класс 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.

Since:: 1.5

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

Modifier and Type	Class	Description
`static class`	`ProcessBuilder.Redirect`	Представляет источник ввода подпроцесса или место назначения вывода подпроцесса.

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

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

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

Modifier and Type	Метод	Описание
`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, создавая цепочку процессов, связанных стандартным выводом и стандартным вводом.

Методы, объявленные в классе java.lang.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.

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

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

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

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

Возвращаемая карта и её коллекции представлений могут не подчиняться общему соглашению методов Object.equals(java.lang.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

END_OF_DOCUMENT_MARKER

redirectError

public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)

Устанавливает место назначения стандартного потока ошибок для данного билдера процесса. Подпроцессы, запущенные позднее методом start() этого объекта, отправляют свои стандартные ошибки в это место назначения.

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

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

Parameters:: destination - новое место назначения стандартного потока ошибок
Returns:: этот билдер процесса
Throws:: IllegalArgumentException - если перенаправление не соответствует допустимому месту назначения данных, то есть имеет тип READ
Since:: 1.7

redirectInput

public ProcessBuilder redirectInput(File file)

Устанавливает источник стандартного входного потока данного билдера процесса на файл.

Это метод-утилита. Вызов вида redirectInput(file) ведет себя точно так же, как вызов redirectInput (Redirect.from(file)).

Parameters:: file - новый источник стандартного входного потока
Returns:: этот билдер процесса
Since:: 1.7

redirectOutput

public ProcessBuilder redirectOutput(File file)

Устанавливает место назначения стандартного выходного потока данного билдера процесса на файл.

Это метод-утилита. Вызов вида redirectOutput(file) ведет себя точно так же, как вызов redirectOutput (Redirect.to(file)).

Parameters:: file - новое место назначения стандартного выходного потока
Returns:: этот билдер процесса
Since:: 1.7

redirectError

public ProcessBuilder redirectError(File file)

Устанавливает место назначения стандартного потока ошибок данного билдера процесса на файл.

Это метод-утилита. Вызов вида redirectError(file) ведет себя точно так же, как вызов redirectError (Redirect.to(file)).

Parameters:: file - новое место назначения стандартного потока ошибок
Returns:: этот билдер процесса
Since:: 1.7

redirectInput

public ProcessBuilder.Redirect redirectInput()

Возвращает источник стандартного входного потока данного билдера процесса. Подпроцессы, запущенные позднее методом start() этого объекта, получают свой стандартный вход из этого источника. Начальное значение равно Redirect.PIPE.

Returns:: источник стандартного входного потока данного билдера процесса
Since:: 1.7

redirectOutput

public ProcessBuilder.Redirect redirectOutput()

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

Returns:: место назначения стандартного выходного потока данного билдера процесса
Since:: 1.7

redirectError

public ProcessBuilder.Redirect redirectError()

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

Returns:: место назначения стандартного потока ошибок данного билдера процесса
Since:: 1.7

inheritIO

public ProcessBuilder inheritIO()

Устанавливает источник и место назначения стандартного потока ввода/вывода подпроцесса равными источнику и месту назначения текущего процесса Java.

Это метод-утилита. Вызов вида

 
 pb.inheritIO()

ведет себя точно так же, как вызов

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

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

Returns:: этот билдер процесса
Since:: 1.7

redirectErrorStream

public boolean redirectErrorStream()

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

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

Returns:: значение свойства redirectErrorStream этого билдера процесса

redirectErrorStream

public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)

Устанавливает свойство redirectErrorStream этого билдера процесса.

Parameters:: redirectErrorStream - новое значение свойства
Returns:: этот билдер процесса

start

public Process start() throws IOException

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

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

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

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

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

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

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

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

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

Implementation Note:

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

Returns:

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

Throws:

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

IndexOutOfBoundsException - если команда является пустым списком (имеет размер 0)

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

IOException - если произошла ошибка ввода/вывода

See Also:

ЗапускПотока

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

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

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

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

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

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

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

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

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

Файл программы операционной системы не был найден.
Доступ к файлу программы был запрещен.
Рабочая директория не существует.
Некорректный символ в аргументе команды, например, 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();
 }

Implementation Note:

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

Parameters:

builders - список ProcessBuilder

Returns:

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

Throws:

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

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

IndexOutOfBoundsException - если команда является пустым списком (имеет размер 0)

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

IOException - если произошла ошибка ввода-вывода

Since:

© 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/lang/ProcessBuilder.html