public final class ProcessBuilder extends Object
各ProcessBuilder
インスタンスは、プロセス属性のコレクションを管理します。start()
メソッドはそれらの属性を使って新しいProcess
インスタンスを作成します。同じインスタンスからstart()
メソッドを繰返し呼び出して、同一の属性または関連する属性を持つ新規サブプロセスを作成できます。
各プロセス・ビルダーは、次のプロセス属性を管理します。
System.getenv()
を参照)。
user.dir
で名前が付けられたディレクトリです。
Process.getOutputStream()
から返される出力ストリームを使用します。ただし標準入力は、redirectInput
を使って別の入力元にリダイレクトできます。この場合、Process.getOutputStream()
から次のようなヌル出力ストリームが返されます。
Process.getInputStream()
およびProcess.getErrorStream()
から返される入力ストリームを使用します。ただし標準出力や標準エラーは、redirectOutput
やredirectError
を使って他の出力先にリダイレクトできます。この場合、Process.getInputStream()
またはProcess.getErrorStream()
、あるいはその両方から、次のようなヌル入力ストリームが返されます。
false
です。つまり、サブプロセスの標準出力とエラー出力は、2つの独立したストリームに送信されます。これらの出力にはProcess.getInputStream()
メソッドとProcess.getErrorStream()
メソッドを使ってアクセスできます。
値がtrue
に設定された場合:
redirectOutput
を使用する
redirectError
メソッドで設定されたリダイレクトは無視される
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(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()
を呼び出してから、環境変数を追加します。
修飾子と型 | クラスと説明 |
---|---|
static class |
ProcessBuilder.Redirect
サブプロセスの入力元またはサブプロセスの出力先を表します。
|
コンストラクタと説明 |
---|
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()
このプロセス・ビルダーの環境の文字列マップのビューを返します。
|
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()
このプロセス・ビルダーの属性を使って新規プロセスを起動します。
|
public ProcessBuilder(List<String> command)
command
リストのコピーを作成しません。以降のリストの更新は、プロセス・ビルダーの状態に反映されます。command
が有効なオペレーティング・システム・コマンドに対応するかどうかはチェックされません。command
- プログラムとプログラムの引数を含むリストNullPointerException
- 引数がnullの場合public ProcessBuilder(String... command)
command
配列と同じ文字列を含む文字列リストに、プロセス・ビルダーのコマンドを同じ順序で設定する簡易コンストラクタです。command
が有効なオペレーティング・システム・コマンドに対応するかどうかはチェックされません。command
- プログラムとプログラムの引数を含む文字列配列public ProcessBuilder command(List<String> command)
command
リストのコピーを作成しません。以降のリストの更新は、プロセス・ビルダーの状態に反映されます。command
が有効なオペレーティング・システム・コマンドに対応するかどうかはチェックされません。command
- プログラムとプログラムの引数を含むリストNullPointerException
- 引数がnullの場合public ProcessBuilder command(String... command)
command
配列と同じ文字列を含む文字列リストにコマンドを同じ順序で設定する簡易メソッドです。command
が有効なオペレーティング・システム・コマンドに対応するかどうかはチェックされません。command
- プログラムとプログラムの引数を含む文字列配列public List<String> command()
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()
メソッドの汎用規約に従わない可能性があります。
返されたマップは、一般にすべてのプラットフォームで大文字と小文字を区別します。
セキュリティ・マネージャが存在する場合は、そのcheckPermission
メソッドがRuntimePermission
("getenv.*")
アクセス権で呼び出されます。これにより、SecurityException
がスローされる可能性があります。
Javaサブプロセスに情報を渡す場合、一般的に環境変数よりもシステム・プロパティが推奨されます。
SecurityException
- セキュリティ・マネージャが存在し、そのcheckPermission
メソッドがプロセス環境へのアクセスを許可しない場合Runtime.exec(String[],String[],java.io.File)
, System.getenv()
public File directory()
start()
メソッドでそれ以降起動されたサブプロセスは、このディレクトリを作業ディレクトリとして使用します。戻り値は、null
の可能性があります。これは、現在のJavaプロセスの作業ディレクトリ(通常はuser.dir
システム・プロパティで指定されたディレクトリ)を子プロセスの作業ディレクトリとして使用することを意味します。public ProcessBuilder directory(File directory)
start()
メソッドでそれ以降起動されたサブプロセスは、このディレクトリを作業ディレクトリとして使用します。引数は、null
の可能性があります。これは、現在のJavaプロセスの作業ディレクトリ(通常はuser.dir
システム・プロパティで指定されたディレクトリ)を子プロセスの作業ディレクトリとして使用することを意味します。directory
- 新規作業ディレクトリpublic ProcessBuilder redirectInput(ProcessBuilder.Redirect source)
start()
メソッドで起動されたサブプロセスは、標準入力をこの入力元から取得します。
sourceがRedirect.PIPE
(初期値)の場合、Process.getOutputStream()
から返される出力ストリームを使ってサブプロセスの標準入力への書込みを行えます。sourceをその他の値に設定した場合、Process.getOutputStream()
からヌル出力ストリームが返されます。
source
- 新しい標準入力元IllegalArgumentException
- リダイレクトがデータの有効な出力先に対応していない場合、つまりその型がWRITE
またはAPPEND
の場合public ProcessBuilder redirectOutput(ProcessBuilder.Redirect destination)
start()
メソッドで起動されたサブプロセスは、標準出力をこの出力先に送信します。
destinationがRedirect.PIPE
(初期値)の場合、Process.getInputStream()
から返される入力ストリームを使ってサブプロセスの標準出力の読取りを行えます。destinationをその他の値に設定した場合、Process.getInputStream()
からヌル入力ストリームが返されます。
destination
- 新しい標準出力先IllegalArgumentException
- リダイレクトがデータの有効な出力先に対応していない場合、つまり次の型を持つ場合: READ
public ProcessBuilder redirectError(ProcessBuilder.Redirect destination)
start()
メソッドで起動されたサブプロセスは、標準エラーをこの出力先に送信します。
destinationがRedirect.PIPE
(初期値)の場合、Process.getErrorStream()
から返される入力ストリームを使ってサブプロセスのエラー出力の読取りを行えます。destinationをその他の値に設定した場合、Process.getErrorStream()
からヌル入力ストリームが返されます。
redirectErrorStream
属性がtrue
に設定されていた場合、このメソッドで設定されたリダイレクトは何の効果も持ちません。
destination
- 新しい標準エラー出力先IllegalArgumentException
- リダイレクトがデータの有効な出力先に対応していない場合、つまり次の型を持つ場合: READ
public ProcessBuilder redirectInput(File file)
これは、簡易メソッドです。redirectInput(file)
の形式で呼び出した場合、呼び出しredirectInput
(Redirect.from(file))
とまったく同じ動作になります。
file
- 新しい標準入力元public ProcessBuilder redirectOutput(File file)
これは、簡易メソッドです。redirectOutput(file)
の形式で呼び出した場合、呼び出しredirectOutput
(Redirect.to(file))
とまったく同じ動作になります。
file
- 新しい標準出力先public ProcessBuilder redirectError(File file)
これは、簡易メソッドです。redirectError(file)
の形式で呼び出した場合、呼び出しredirectError
(Redirect.to(file))
とまったく同じ動作になります。
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()
これは、簡易メソッドです。次の形式の呼出しは、
pb.inheritIO()
次の呼び出しと正確に同じ動作になります。
pb.redirectInput(Redirect.INHERIT)
.redirectOutput(Redirect.INHERIT)
.redirectError(Redirect.INHERIT)
この動作は、ほとんどのオペレーティング・システム・コマンド・インタプリタや標準Cライブラリ関数system()
と同等のものになります。public boolean redirectErrorStream()
このプロパティがtrue
の場合、このオブジェクトのstart()
メソッドでそれ以降起動されたサブプロセスにより生成されるエラー出力は、標準出力とマージされます。これにより、Process.getInputStream()
メソッドを使って、エラー出力と標準出力の両方を読み取ることができます。マージにより、エラー・メッセージと対応する出力との相関を示すのが容易になります。初期値はfalse
です。
redirectErrorStream
プロパティpublic ProcessBuilder redirectErrorStream(boolean redirectErrorStream)
redirectErrorStream
プロパティを設定します。
このプロパティがtrue
の場合、このオブジェクトのstart()
メソッドでそれ以降起動されたサブプロセスにより生成されるエラー出力は、標準出力とマージされます。これにより、Process.getInputStream()
メソッドを使って、エラー出力と標準出力の両方を読み取ることができます。マージにより、エラー・メッセージと対応する出力との相関を示すのが容易になります。初期値はfalse
です。
redirectErrorStream
- 新しいプロパティの値public Process start() throws IOException
新しいプロセスは、directory()
で与えられる作業ディレクトリ内で、environment()
で与えられるプロセス環境の下、command()
で与えられるコマンドと引数を呼び出します。
このメソッドは、コマンドが有効なオペレーティング・システム・コマンドであることをチェックします。どのコマンドが有効かはシステム依存ですが、コマンドは少なくともnull以外の文字列の空でないリストである必要があります。
一部のオペレーティング・システムでは、プロセスを起動するために最小限のシステム依存環境変数のセットが必要となる可能性があります。このため、プロセス・ビルダーのenvironment()
に含まれていない追加の環境変数設定をサブプロセスが継承する可能性があります。
セキュリティ・マネージャが存在する場合はそのcheckExec
メソッドが呼び出されますが、その際、このオブジェクトのcommand
配列の最初のコンポーネントが引数として指定されます。これにより、SecurityException
がスローされる可能性があります。
オペレーティング・システム・プロセスの起動はきわめてシステムに依存します。発生する可能性がある不具合は次のとおりです。
以上のケースでは、例外がスローされます。例外の正確な特性はシステムに依存しますが、これは常にIOException
のサブクラスになります。
このプロセス・ビルダーへの以降の変更は、返されたProcess
に影響を及ぼしません。
Process
オブジェクトNullPointerException
- コマンド・リストの要素がnullの場合IndexOutOfBoundsException
- コマンドが空(サイズが0
)のリストの場合SecurityException
- セキュリティ・マネージャが存在していて、
checkExec
メソッドがサブプロセスの作成を許可しない場合、または
checkRead
メソッドがファイルからの読取りアクセスを拒否する場合、または
checkWrite
メソッドがファイルへの書込みアクセスを拒否する場合
IOException
- 入出力エラーが発生した場合Runtime.exec(String[], String[], java.io.File)
バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。