Класс ProcessBuilder

public ProcessBuilder(List<String> command)

Создаёт обработчик процесса с указанной программой операционной системы и аргументами. Этот конструктор не создаёт копию command списка. Последующие изменения в списке будут отражены в состоянии обработчика процесса. Не проверяется, соответствует ли command допустимой команде операционной системы.

public ProcessBuilder(String... command)

Создаёт обработчик процесса с указанной программой операционной системы и аргументами. Это удобный конструктор, который устанавливает команду обработчика процесса в список строк, содержащий те же строки, что и command массив, в том же порядке. Не проверяется, соответствует ли command допустимой команде операционной системы.

public ProcessBuilder command(List<String> command)

Устанавливает программу и аргументы операционной системы для обработчика процесса. Этот метод не создаёт копию command списка. Последующие изменения в списке будут отражены в состоянии обработчика процесса. Не проверяется, соответствует ли command допустимой команде операционной системы.

public ProcessBuilder command(String... command)

Устанавливает программу и аргументы операционной системы для обработчика процесса. Это удобный метод, который устанавливает команду в список строк, содержащий те же строки, что и command массив, в том же порядке. Не проверяется, соответствует ли command допустимой команде операционной системы.

public List<String> command()

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

public Map<String,String> environment()

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

Возвращаемый объект можно изменить с помощью обычных операций Map. Эти изменения будут видны для подпроцессов, запущенных с помощью метода start(). Два ProcessBuilder экземпляра всегда содержат независимые среды процессов, поэтому изменения в возвращаемой карте никогда не будут отражены в любом другом экземпляре ProcessBuilder или значениях, возвращаемых System.getenv.

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

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

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

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

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

Возвращаемая карта обычно регистрозависимая на всех платформах.

Если существует менеджер безопасности, вызывается его метод checkPermission с разрешением RuntimePermission("getenv.*"). Это может привести к исключению SecurityException.

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

public File directory()

Возвращает рабочую директорию этого обработчика процесса. Подпроцессы, запущенные позднее этим объектом с помощью метода start(), будут использовать её в качестве своей рабочей директории. Возвращаемое значение может быть null — это означает использовать рабочую директорию текущего процесса Java, обычно директорию, названную системной переменной user.dir, как рабочую директорию дочернего процесса.

public ProcessBuilder directory(File directory)

Устанавливает рабочую директорию этого обработчика процесса. Подпроцессы, запущенные позднее этим объектом с помощью метода start(), будут использовать её в качестве своей рабочей директории. Аргумент может быть null — это означает использовать рабочую директорию текущего процесса Java, обычно директорию, названную системной переменной user.dir, как рабочую директорию дочернего процесса.

public ProcessBuilder redirectInput(ProcessBuilder.Redirect source)

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

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

public ProcessBuilder redirectOutput(ProcessBuilder.Redirect destination)

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

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

public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)

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

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

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

public ProcessBuilder redirectInput(File file)

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

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

public ProcessBuilder redirectOutput(File file)

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

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

public ProcessBuilder redirectError(File file)

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

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

public ProcessBuilder.Redirect redirectInput()

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

public ProcessBuilder.Redirect redirectOutput()

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

public ProcessBuilder.Redirect redirectError()

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

public ProcessBuilder inheritIO()

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

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

 
 pb.inheritIO()
 

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

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

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

public boolean redirectErrorStream()

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

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

public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)

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

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

public Process start() throws IOException

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

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

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

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

Если существует менеджер безопасности, вызывается его метод checkExec с первым компонентом массива command этого объекта в качестве аргумента. Это может привести к тому, что будет брошено исключение SecurityException.

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

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

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

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

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

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

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

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

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

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

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

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

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

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