- java.lang.Object
-
- jdk.incubator.http.HttpRequest
-
public abstract class HttpRequest extends Object
サーバーに送信できる1つのHTTPリクエストを表します。
インキュベーション機能。将来のリリースで削除されます。HttpRequest
インスタンスは、HttpRequest
buildersから構築されます。HttpRequest
ビルダーは、HttpRequest.newBuilder
を呼び出して取得します。 リクエストURI、ヘッダーと本文を設定できます。 リクエスト・ボディは、DELETE
、POST
、またはPUT
メソッドに提供されるHttpRequest.BodyPublisher
オブジェクトを介して提供されます。GET
は身体をとりません。 ビルダーに必要なすべてのパラメータが設定されると、HttpRequest.Builder.build()
が呼び出されてHttpRequest
が返されます。 いくつかのパラメータが異なる複数の関連するリクエストを構築するために、ビルダーを複数回コピーして変更することもできます。2つの単純なHTTPインタラクションの例を以下に示します:
HttpClient client = HttpClient.newHttpClient(); // GET HttpResponse<String> response = client.send( HttpRequest .newBuilder(new URI("http://www.foo.com/")) .headers("Foo", "foovalue", "Bar", "barvalue") .GET() .build(), BodyHandler.asString() ); int statusCode = response.statusCode(); String body = response.body(); // POST HttpResponse<Path> response = client.send( HttpRequest .newBuilder(new URI("http://www.foo.com/")) .headers("Foo", "foovalue", "Bar", "barvalue") .POST(BodyPublisher.fromString("Hello world")) .build(), BodyHandler.asFile(Paths.get("/path")) ); int statusCode = response.statusCode(); Path body = response.body(); // should be "/path"
HttpClient
で次のいずれかのメソッドを呼び出すと、リクエストが送信され、レスポンスが取得されます。HttpClient.send(HttpRequest, HttpResponse.BodyHandler)
は、リクエスト全体が送信され、レスポンスが受信されるまでブロックします。HttpClient.sendAsync(HttpRequest,HttpResponse.BodyHandler)
はリクエストを送信し、レスポンスを非同期的に受信します。CompletableFuture
<HttpResponse
>を使用してすぐに戻します。HttpClient.sendAsync(HttpRequest, HttpResponse.MultiSubscriber)
は複数のレスポンスを期待して非同期にリクエストを送信します。 この機能は、HTTP/2サーバー・プッシュと最も関連性がありますが、単一のレスポンス(HTTP/1.1またはHTTP/2)でも使用できます。
HttpResponse
が受信されると、ヘッダー、レスポンス・コード、本文(typically)が利用可能になります。 本文が読み込まれたかどうかは、レスポンス本体の型<T>
によって決まります。 後述の説明を参照してください。同期と非同期の使用方法については、以下を参照してください。
リクエスト団体
リクエスト・ボディは、
HttpRequest.BodyPublisher
で提供される以下のコンビニエンス・リクエスト・パブリッシャ実装の1つを使用して送信できます。 また、カスタムのPublisher実装を使用することもできます。- バイト配列からの
fromByteArray(byte[])
- バイト配列のIterableからの
fromByteArrays(Iterable)
- 指定されたパスにあるファイルからの
fromFile(Path)
- Stringからの
fromString(String)
- サプライヤから取得したInputStreamからの
fromInputStream
(Supplier
<InputStream
>) HttpRequest.BodyPublisher.noBody()
リクエスト本文は送信されません
レスポンス機関
レスポンス機関は2つのレベルで扱われます。 リクエストを送信するときは、レスポンス本文ハンドラが指定されます。 これは、レスポンス・ステータス・コードとヘッダーが受信されると呼び出される関数(HttpResponse.BodyHandler)です。 この関数は、
HttpResponse.BodySubscriber
<T>
を返すと予想され、レスポンス本文を読み取ってTのインスタンスに変換します。 これが発生すると、レスポンスはHttpResponse
で利用可能になり、HttpResponse.body()
を呼び出して実際の本文を取得することができます。HttpResponse.BodySubscriber
とHttpResponse.BodyHandler
の両方の使用法と実装例は、HttpResponse
で提供されています:「あらかじめ定義された本文ハンドラの一部」
BodyHandler.asByteArray()
は本文をバイト配列に格納BodyHandler.asString()
は本文をStringとして格納BodyHandler.asFile(Path)
は、本文を名前付きファイルに格納BodyHandler.discard()
はレスポンス本文を破棄し、代わりに指定された値を返します。
複数回答
HTTP/2では、サーバーがメインのレスポンスとゼロ以上の追加のレスポンス(サーバー・プッシュと呼ばれる)をクライアントが開始したリクエストに返すことが可能です。 これらは、
HttpResponse.MultiSubscriber
という特別なレスポンス・サブスクライバを使用して処理されます。ブロッキング/非同期動作とスレッドの使用
リクエスト送信には2つのスタイルがあります: synchronousとasynchronousです。
HttpClient.send(HttpRequest, HttpResponse.BodyHandler)
は、リクエストが送信され、レスポンスが受信されるまで、呼び出しスレッドをブロックします。HttpClient.sendAsync(HttpRequest, HttpResponse.BodyHandler)
は非同期で、すぐにCompletableFuture
<HttpResponse
>を返し、このオブジェクトがを完了(おそらく別のスレッドに)するとレスポンスを受信しました。HttpClient.sendAsync(HttpRequest, HttpResponse.MultiSubscriber)
はマルチ・レスポンスの変形であり、非同期です。CompletableFuture
のインスタンスは、いくつかの非同期タスク間の依存関係を宣言するためにさまざまな方法で組み合わせることができ、最大レベルの並列処理を利用することができます。セキュリティ・マネージャが存在する場合、HTTPクライアントがメソッドを送信することによってセキュリティ検査が実行されます。 宛先サーバーにアクセスするには適切な
URLPermission
が必要で、プロキシ・サーバーが構成されている場合はプロキシ・サーバーにアクセスする必要があります。 プロキシへのアクセスに使用されるURLPermission
形式は、メソッド・パラメータ"CONNECT"
(すべての種類のプロキシ処理)と、形式"socket://host:port"
のURL文字列を使用します。ここで、hostとportはプロキシ・アドレスを指定します。この実装では、明示的なexecutorが
HttpClient
に設定されておらず、セキュリティ・マネージャがインストールされている場合、デフォルトのエグゼキュータは、パーミッションが付与されていないコンテキストで非同期および従属のタスクを実行します。 特権を必要とする操作を実行する場合、カスタム「ボディ・パブリッシャをリクエスト」、「レスポンス本文ハンドラ」、「レスポンス本文サブスクライバ」、および「WebSocketリスナー」は、適切な「特権的なコンテキスト」内で行う必要があります。例
HttpClient client = HttpClient .newBuilder() .build(); HttpRequest request = HttpRequest .newBuilder(new URI("http://www.foo.com/")) .POST(BodyPublisher.fromString("Hello world")) .build(); HttpResponse<Path> response = client.send(request, BodyHandler.asFile(Paths.get("/path"))); Path body = response.body();
非同期の例
send
の代わりに(HttpRequest, HttpResponse.BodyHandler) sendAsync
が使用されている場合、上記の例は非同期で動作します。この場合、返されるオブジェクトはHttpResponse
の代わりにCompletableFuture
<HttpResponse>
です。 次の例は、複数のリクエストを非同期で送信する方法を示しています。 また、CompletableFuture
の多くのメソッドの1つを使用して、依存関係のない非同期操作(レスポンスを受信し、レスポンス本文を受信)を簡単にチェーンする方法を示します。// fetch a list of target URIs asynchronously and store them in Files. List<URI> targets = ... List<CompletableFuture<File>> futures = targets .stream() .map(target -> client .sendAsync( HttpRequest.newBuilder(target) .GET() .build(), BodyHandler.asFile(Paths.get("base", target.getPath()))) .thenApply(response -> response.body()) .thenApply(path -> path.toFile())) .collect(Collectors.toList()); // all async operations waited for here CompletableFuture.allOf(futures.toArray(new CompletableFuture<?>[0])) .join(); // all elements of futures have completed and can be examined. // Use File.exists() to check whether file was successfully downloaded
特に明記されていない限り、
null
のパラメータ値により、このクラスのメソッドはNullPointerException
をスローします。- 導入されたバージョン:
- 9
-
-
ネストされたクラスのサマリー
ネストされたクラス 修飾子と型 クラス 説明 static interface
HttpRequest.BodyPublisher
高水準のJavaオブジェクトをリクエスト本体として送信するのに適したバイト・バッファのフローに変換するパブリッシャ。static class
HttpRequest.Builder
「HTTPリクエスト」の作成者。
-
コンストラクタのサマリー
コンストラクタ 修飾子 コンストラクタ 説明 protected
HttpRequest()
HttpRequestを作成します。
-
メソッドのサマリー
すべてのメソッド staticメソッド インスタンス・メソッド 抽象メソッド 具象メソッド 修飾子と型 メソッド 説明 abstract Optional<HttpRequest.BodyPublisher>
bodyPublisher()
このリクエストで設定されたHttpRequest.BodyPublisher
を含むOptional
を返します。boolean
equals(Object obj)
このHTTPリクエスト・インスタンスが指定されたオブジェクトと等しいかどうかをテストします。abstract boolean
expectContinue()
expect continue
の設定を返します。int
hashCode()
このHTTPリクエスト・インスタンスのハッシュ・コードを計算します。abstract HttpHeaders
headers()
(user-accessible)リクエスト・ヘッダーは、このリクエストが送信された(または)でした。abstract String
method()
このリクエストのリクエスト・メソッドを返します。static HttpRequest.Builder
newBuilder()
HttpRequest
Builderを作成します。static HttpRequest.Builder
newBuilder(URI uri)
HttpRequest
Builderを作成します。abstract Optional<Duration>
timeout()
このリクエスト・タイムアウト期間を含むOptional
を返します。abstract URI
uri()
このリクエスト・リクエストURI
を返します。abstract Optional<HttpClient.Version>
version()
このHttpRequest
にリクエストされるHTTPプロトコル・バージョンを含むOptional
を返します。
-
-
-
メソッドの詳細
-
newBuilder
public static HttpRequest.Builder newBuilder(URI uri)
HttpRequest
Builderを作成します。- パラメータ:
uri
- リクエストURI- 戻り値:
- 新しいリクエスト・ビルダー
- 例外:
IllegalArgumentException
- URIスキームがサポートされていない場合。
-
newBuilder
public static HttpRequest.Builder newBuilder()
HttpRequest
Builderを作成します。- 戻り値:
- 新しいリクエスト・ビルダー
-
bodyPublisher
public abstract Optional<HttpRequest.BodyPublisher> bodyPublisher()
このリクエストで設定されたHttpRequest.BodyPublisher
を含むOptional
を返します。BodyPublisher
がリクエスト・ビルダーに設定されていない場合、Optional
は空です。- 戻り値:
- このリクエストを含む
Optional
BodyPublisher
-
method
public abstract String method()
このリクエストのリクエスト・メソッドを返します。 明示的に設定されていない場合、任意のリクエストに対するデフォルトのメソッドは"GET"です。- 戻り値:
- このリクエスト・メソッド
-
timeout
public abstract Optional<Duration> timeout()
このリクエスト・タイムアウト期間を含むOptional
を返します。 リクエスト・ビルダーでタイムアウト時間が設定されていない場合、Optional
は空です。- 戻り値:
- このリクエスト・タイムアウト時間を含む
Optional
-
expectContinue
public abstract boolean expectContinue()
expect continue
の設定を返します。- 戻り値:
- このリクエストは設定を続けることを期待しています
-
uri
public abstract URI uri()
このリクエスト・リクエストURI
を返します。- 戻り値:
- このリクエストURI
-
version
public abstract Optional<HttpClient.Version> version()
このHttpRequest
にリクエストされるHTTPプロトコル・バージョンを含むOptional
を返します。 リクエスト・ビルダーにバージョンが設定されていない場合、Optional
は空です。 その場合、リクエストされたバージョンは送信するHttpClient
のバージョンになります。 実際に使用されたバージョンを確認するには、対応するHttpResponse
を問合せする必要があります。- 戻り値:
- HTTPプロトコル・バージョン
-
headers
public abstract HttpHeaders headers()
(user-accessible)リクエスト・ヘッダーは、このリクエストが送信された(または)でした。- 戻り値:
- このリクエストHttpHeaders
-
equals
public final boolean equals(Object obj)
このHTTPリクエスト・インスタンスが指定されたオブジェクトと等しいかどうかをテストします。指定されたオブジェクトが
HttpRequest
でない場合、このメソッドはfalse
を返します。 URI、メソッド、およびヘッダー・フィールドがすべて等しい場合、2つのHTTPリクエストは等しいです。このメソッドは
Object.equals
メソッドの汎用規約を満たします。- オーバーライド:
equals
、クラス:Object
- パラメータ:
obj
- このオブジェクトが比較されるオブジェクト- 戻り値:
- 指定されたオブジェクトがこのHTTPリクエストと等しい
HttpRequest
である場合にのみtrue
- 関連項目:
Object.hashCode()
、HashMap
-
hashCode
public final int hashCode()
このHTTPリクエスト・インスタンスのハッシュ・コードを計算します。ハッシュ・コードは、HTTPリクエストのURI、メソッド、およびヘッダー・コンポーネントに基づいており、
Object.hashCode
メソッドの汎用規約を満たしています。- オーバーライド:
hashCode
、クラス:Object
- 戻り値:
- このHTTPリクエストのハッシュ・コード値
- 関連項目:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
-