java.lang
クラス ProcessBuilder

java.lang.Object
  java.lang.ProcessBuilder

public final class ProcessBuilder
extends Object

このクラスは、オペレーティングシステムのプロセスの作成に使用されます。

各 ProcessBuilder インスタンスは、プロセス属性のコレクションを管理します。start() メソッドは、これらの属性を持つ新規 Process インスタンスを作成します。同じインスタンスから start() メソッドを繰り返し呼び出して、同一の属性または関連する属性を持つ新規サブプロセスを作成できます。

各プロセスビルダは、次のプロセス属性を管理します。

• 「コマンド」。呼び出される外部プログラムファイルと、その引数 (存在する場合) を示す文字列のリストです。どの文字列リストが有効なオペレーティングシステムコマンドを表すかは、システムに応じて異なります。たとえば、概念上の引数がリストの要素となるのが一般的ですが、プログラムがコマンドライン文字列自体をトークン化することが要求されるオペレーティングシステムがあります。このようなシステムの Java 実装では、正確に 2 つの要素を含むコマンドが必要になる場合があります。
• 「環境」。環境は「変数」から「値」へのシステム依存のマッピングです。初期値は、現在のプロセスの環境のコピーです (System.getenv() を参照)。
• 「作業ディレクトリ」。デフォルト値は、現在のプロセスの現在の作業ディレクトリです。通常、このディレクトリはシステムプロパティ user.dir で名前が付けられたディレクトリです。
• redirectErrorStream プロパティ。初期状態では、このプロパティは false です。つまり、サブプロセスの標準出力とエラー出力は、2 つの独立したストリームに送信されます。これらの出力には Process.getInputStream() メソッドと Process.getErrorStream() メソッドを使ってアクセスできます。この値を true に設定すると、標準エラーは標準出力にマージされます。マージすると、対応する出力を含むエラーメッセージとの相関を示すのが容易になります。この場合、マージされたデータは、Process.getInputStream() が返すストリームから読み取ることができますが、Process.getErrorStream() が返すストリームを読み取ると、ファイルの終わりにすぐ達します。

プロセスビルダの属性を変更すると、属性を変更したオブジェクトの start() メソッドでそれ以降起動されるプロセスに影響がありますが、それ以前に起動されたプロセスや Java プロセス自体には影響ありません。

ほとんどのエラーチェックは start() メソッドで実行されます。 start() が失敗するように、オブジェクトの状態を変更することができます。たとえば、コマンド属性を空のリストに設定すると、 start() が呼び出されない限り、例外はスローされません。

このクラスは同期化されません。複数のスレッドが ProcessBuilder インスタンスに同時にアクセスし、少なくとも 1 つのスレッドが構造的に 1 つの属性を変更した場合、変更された属性は外部で同期化されなければなりません。

デフォルトの作業ディレクトリと環境を使用する新しいプロセスを起動するのは、次に示すように容易です。

 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("myDir");
 Process p = pb.start();
 

環境変数の明示的セットを持つプロセスを起動するには、まず Map.clear() を呼び出してから、環境変数を追加します。

導入されたバージョン:

1.5

コンストラクタの概要

ProcessBuilder(List<String> command)
指定されたオペレーティングシステムプログラムと引数を持つプロセスビルダを構築します。

ProcessBuilder(String... command)
指定されたオペレーティングシステムプログラムと引数を持つプロセスビルダを構築します。

メソッドの概要

List<String>	command() プロセスビルダのオペレーティングシステムプログラムと引数を返します。
ProcessBuilder	command(List<String> command) プロセスビルダのオペレーティングシステムプログラムと引数を設定します。
ProcessBuilder	command(String... command) このプロセスビルダのオペレーティングシステムプログラムと引数を設定します。
File	directory() このプロセスビルダの作業ディレクトリを返します。
ProcessBuilder	directory(File directory) このプロセスビルダの作業ディレクトリを設定します。
Map<String,String>	environment() このプロセスビルダの環境の文字列マップのビューを返します。
boolean	redirectErrorStream() このプロセスビルダが標準エラーと標準出力をマージするかどうかを判定します。
ProcessBuilder	redirectErrorStream(boolean redirectErrorStream) このプロセスビルダの redirectErrorStream プロパティを設定します。
Process	start() このプロセスビルダの属性を使って新規プロセスを起動します。

クラス java.lang.Object から継承されたメソッド

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

コンストラクタの詳細

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

このプロセスビルダの環境の文字列マップのビューを返します。 プロセスビルダが作成されるたびに、環境は現在のプロセス環境のコピーに初期化されます (System.getenv() を参照)。このオブジェクトの start() メソッドで起動される以降のサブプロセスは、このマップを環境として使用します。

返されたオブジェクトは、通常の Map オペレーションを使って変更できます。これらの変更は、start() メソッドを使って起動されたサブプロセスで可視です。2 つの ProcessBuilder インスタンスは常に独立したプロセス環境を持っています。このため、返されたマップは、ほかの ProcessBuilder インスタンスや、System.getenv で返された値に反映されることはありません。

システムが環境変数をサポートしていない場合は、空のマップが返されます。

返されたマップは、null のキーや値を許容しません。null のキーや値を挿入したり、これらがあるか照会すると、NullPointerException がスローされます。String 型ではないキーや値があるか照会すると、ClassCastException がスローされます。

返されたマップの動作はシステムに依存します。環境変数の変更を許可しないシステムがあれば、特定の変数名や値が禁止されるシステムもあります。この理由から、オペレーティングシステムで変更が許可されていない場合、マップを変更しようとすると、UnsupportedOperationException や IllegalArgumentException で失敗する可能性があります。

環境変数名と環境変数の値の外部形式はシステムに依存するので、環境変数名と環境変数の値と Java の Unicode 文字列との間に 1 対 1 のマッピング関係がない可能性があります。その場合でも、Java コードで変更されていない環境変数が、サブプロセスでも変更されていないネイティブな表現を持つようにマップは実装されます。

返されたマップとそのコレクションビューは、Object.equals(java.lang.Object) メソッドと Object.hashCode() メソッドの汎用規約に従わない可能性があります。

返されたマップは、一般にすべてのプラットフォームで大文字と小文字を区別します。

セキュリティマネージャが存在する場合は、RuntimePermission("getenv.*") アクセス権を使って checkPermission メソッドが呼び出されます。この結果、SecurityException がスローされることがあります。

Java サブプロセスに情報を渡す場合、環境変数よりもシステムプロパティが推奨されています。

戻り値:

このプロセスビルダの環境

例外:

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 - 新規作業ディレクトリ

戻り値:

このプロセスビルダ

redirectErrorStream

public boolean redirectErrorStream()

このプロセスビルダが標準エラーと標準出力をマージするかどうかを判定します。

このプロパティが true の場合、このオブジェクトの start() メソッドでそれ以降起動されたサブプロセスにより生成されるエラー出力は、標準出力とマージされます。これにより、Process.getInputStream() メソッドを使って、エラー出力と標準出力の両方を読み取ることができます。マージにより、エラーメッセージと対応する出力との相関を示すのが容易になります。初期値は false です。

戻り値:

このプロセスビルダの redirectErrorStream プロパティ

redirectErrorStream

public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)

このプロセスビルダの redirectErrorStream プロパティを設定します。

このプロパティが true の場合、このオブジェクトの start() メソッドでそれ以降起動されたサブプロセスにより生成されるエラー出力は、標準出力とマージされます。これにより、Process.getInputStream() メソッドを使って、エラー出力と標準出力の両方を読み取ることができます。マージにより、エラーメッセージと対応する出力との相関を示すのが容易になります。初期値は false です。

パラメータ:

redirectErrorStream - 新しいプロパティの値

戻り値:

このプロセスビルダ

start

public Process start()
              throws IOException

このプロセスビルダの属性を使って新規プロセスを起動します。

この新規プロセスは、directory() で指定された作業ディレクトリの、environment() で指定されたプロセス環境を持つ、command() で指定されたコマンドと引数を呼び出します。

このメソッドは、コマンドが有効な オペレーティングシステムコマンドであることをチェックします。どのコマンドが有効かどうかはシステム依存ですが、コマンドは少なくとも null 以外の文字列の空でないリストでなければなりません。

セキュリティマネージャが存在する場合は、command 配列の最初のコンポーネントを引数として使って checkExec メソッドが呼び出されます。この結果、SecurityException がスローされることがあります。

オペレーティングシステムプロセスの起動は極めてシステムに依存します。発生する可能性がある不具合は次のとおりです。

• オペレーティングシステムプログラムファイルが見つからなかった
• プログラムファイルへのアクセス権が拒否された
• 作業ディレクトリが存在しない

以上のケースでは、例外がスローされます。例外の正確な特性はシステムに依存しますが、例外は常に IOException のサブクラスになります。

このプロセスビルダへの以降の変更は、返された Process に影響を及ぼしません。

戻り値:

サブプロセスを管理するための新規 Process オブジェクト

例外:

NullPointerException - コマンドリストの要素が null の場合

IndexOutOfBoundsException - コマンドが空 (サイズが 0) のリストの場合

SecurityException - セキュリティマネージャが存在し、checkExec メソッドがサブプロセスの作成を許可しない場合

IOException - 入出力エラーが発生した場合

関連項目:

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