Класс ProcessBuilder

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

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

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

• команда, список строк, определяющий файл внешней программы для вызова и её аргументы, если таковые имеются. Список строк, представляющих допустимую команду операционной системы, зависит от системы. Например, часто каждый концептуальный аргумент является элементом этого списка, но существуют операционные системы, где программы ожидают токенизацию строк командной строки — в такой системе 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() перед добавлением переменных среды.

Конструкторы

ProcessBuilder

public ProcessBuilder(List<String> command)

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

Параметры:

command - список, содержащий программу и её аргументы

Исключения:

NullPointerException - если аргумент равен null

ProcessBuilder

public ProcessBuilder(String... command)

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

Параметры:

command - массив строк, содержащий программу и её аргументы

Методы

command

public ProcessBuilder command(List<String> command)

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

Параметры:

command - список, содержащий программу и её аргументы

Возвращает:

этот обработчик процесса

Исключения:

NullPointerException - если аргумент равен null

command

public ProcessBuilder command(String... command)

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

Параметры:

command - массив строк, содержащий программу и её аргументы

Возвращает:

этот обработчик процесса

command

public List<String> command()

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

Возвращает:

программа и её аргументы обработчика процесса

environment

public Map<String,String> environment()

Возвращает:

среда этого обработчика процесса

Исключения:

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(ProcessBuilder.Redirect source)

Параметры:

source - новый источник стандартного ввода

Возвращает:

этот обработчик процесса

Исключения:

IllegalArgumentException - если перенаправление не соответствует допустимому источнику данных, то есть имеет тип WRITE или APPEND

С:

1.7

redirectOutput

public ProcessBuilder redirectOutput(ProcessBuilder.Redirect destination)

Параметры:

destination - новое место назначения стандартного вывода

Возвращает:

этот обработчик процесса

Исключения:

IllegalArgumentException - если перенаправление не соответствует допустимому месту назначения данных, то есть имеет тип READ

С:

1.7

redirectError

public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)

Параметры:

destination - новое место назначения стандартной ошибки

Возвращает:

этот обработчик процесса

Исключения:

IllegalArgumentException - если перенаправление не соответствует допустимому месту назначения данных, то есть имеет тип READ

С:

1.7

redirectInput

public ProcessBuilder redirectInput(File file)

Параметры:

file - новый стандартный источник ввода

Возвращает:

этот обработчик процессов

С:

1.7

redirectOutput

public ProcessBuilder redirectOutput(File file)

Параметры:

file - новое стандартное направление вывода

Возвращает:

этот обработчик процессов

С:

1.7

redirectError

public ProcessBuilder redirectError(File 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()

pb.inheritIO()

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

Возвращает:

этот обработчик процессов

С:

1.7

redirectErrorStream

public boolean redirectErrorStream()

Возвращает:

свойство redirectErrorStream этого обработчика процессов

redirectErrorStream

public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)

Параметры:

redirectErrorStream - новое значение свойства

Возвращает:

этот обработчик процессов

start

public Process start()
              throws IOException

Возвращает:

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

Исключение:

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

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

SecurityException - если менеджер безопасности существует и

• его метод checkExec не разрешает создание подпроцесса или
• стандартный ввод подпроцесса был перенаправлен из файла с помощью checkRead и метод менеджера безопасности checkWrite запрещает чтение файла, или
• стандартный вывод или вывод ошибок подпроцесса был перенаправлен в файл с помощью IOException и метод менеджера безопасности Runtime.exec(String[], String[], java.io.File) запрещает запись в файл

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

См. также:

Runtime.exec(String[], String[], java.io.File)