モジュール java.net.http

パッケージ java.net.http

インタフェースHttpRequest.Builder

含まれているクラス:

HttpRequest

public static interface HttpRequest.Builder

「HTTPリクエスト」のビルダー。

HttpRequest.Builderのインスタンスは、HttpRequest.newBuilder()、HttpRequest.newBuilder(URI)またはHttpRequest.newBuilder(HttpRequest, BiPredicate)をコールして作成します。

このビルダーを使用して、次のようなリクエストごとの状態を構成できます: リクエストURI、リクエスト・メソッド(明示的に設定しないかぎり、デフォルトはGETです)、特定のリクエスト・ヘッダーなど。各setterメソッドは、ビルダーの状態を変更し、同じインスタンスを返します。 メソッドは同期されず、外部同期がない複数のスレッドからコールしないでください。 buildメソッドは、起動されるたびに新しいHttpRequestを返します。 一度構築された HttpRequestは不変であり、複数回送信できます。

すべてのリクエスト・ヘッダーがユーザー・コードによって設定されるわけではないことに注意してください。 認証、リダイレクションおよびCookie管理に関連するヘッダーなど、セキュリティ上の理由で制限されるものもありますが、直接ユーザー・セット・ヘッダーを使用するのではなく、特定のAPIによって管理されます。

導入されたバージョン:

11

メソッドのサマリー

修飾子と型	メソッド	説明
HttpRequest	build()	HttpRequestを作成して返します。
HttpRequest.Builder	copy()	現在の状態に基づいて、このBuilderの正確な複製コピーを返します。
HttpRequest.Builder	DELETE()	このビルダーのリクエスト・メソッドをDELETEに設定します。
HttpRequest.Builder	expectContinue(boolean enable)	サーバーが本文を送信する前にリクエストを確認するようリクエストします。
HttpRequest.Builder	GET()	このビルダーのリクエスト・メソッドをGETに設定します。
default HttpRequest.Builder	HEAD()	このビルダーのリクエスト・メソッドをHEADに設定します。
HttpRequest.Builder	header(String name, String value)	指定された名前値ペアを、このリクエストのヘッダー・セットに追加します。
HttpRequest.Builder	headers(String... headers)	指定された名前と値のペアを、このリクエストのヘッダーのセットに追加します。
HttpRequest.Builder	method(String method, HttpRequest.BodyPublisher bodyPublisher)	このビルダーのリクエスト・メソッドおよびリクエスト本文を指定された値に設定します。
HttpRequest.Builder	POST(HttpRequest.BodyPublisher bodyPublisher)	このBuilderのリクエスト・メソッドをPOSTに設定し、リクエスト本文パブリッシャを指定された値に設定します。
HttpRequest.Builder	PUT(HttpRequest.BodyPublisher bodyPublisher)	このBuilderのリクエスト・メソッドをPUTに設定し、リクエスト本文パブリッシャを指定された値に設定します。
HttpRequest.Builder	setHeader(String name, String value)	指定された名前値ペアを、このリクエストのヘッダーのセットに設定します。
HttpRequest.Builder	timeout(Duration duration)	このリクエストのタイムアウトを設定します。
HttpRequest.Builder	uri(URI uri)	このHttpRequestのリクエストURIを設定します。
HttpRequest.Builder	version(HttpClient.Version version)	このリクエストの優先HttpClient.Versionを設定します。

メソッドの詳細

uri

HttpRequest.Builder uri(URI uri)

このHttpRequestのリクエストURIを設定します。

パラメータ:

uri - リクエストURI

戻り値:

このビルダー

例外:

IllegalArgumentException - URIスキームがサポートされていない場合

expectContinue

HttpRequest.Builder expectContinue(boolean enable)

サーバーが本文を送信する前にリクエストを確認するようリクエストします。 デフォルトでは、出力が無効化されます。 有効になっている場合、クライアントはリクエスト本文を送信する前に、エラー・レスポンスまたは100 Continueレスポンスを送信するようリクエストされます。 これは、この暫定的なレスポンスが受信されるまでリクエストの発行元が呼び出されないことを意味します。

パラメータ:

enable - Expectを引き続き送信する場合はtrue

戻り値:

このビルダー

version

HttpRequest.Builder version(HttpClient.Version version)

このリクエストの優先HttpClient.Versionを設定します。

対応するHttpResponseは、実際に使用されたバージョンを確認する必要があります。 バージョンがリクエストで設定されていない場合、リクエストされたバージョンは送信元のHttpClientのバージョンになります。

パラメータ:

version - リクエストされたHTTPプロトコルのバージョン

戻り値:

このビルダー

header

HttpRequest.Builder header(String name, String value)

指定された名前値ペアを、このリクエストのヘッダー・セットに追加します。 指定された値がその名前の値のリストに追加されます。

実装上のノート:

HTTPクライアントが値自体を決定する可能性があるため、実装では一部のヘッダー名または値を制限することを選択できます。 たとえば、"Content-Length"は、リクエストPublisherによって決定されます。 このような場合、HttpRequest.Builderの実装では、そのようなヘッダーがビルダーに渡されると、IllegalArgumentExceptionをスローするように選択できます。

パラメータ:

name - ヘッダー名

value - ヘッダー値

戻り値:

このビルダー

例外:

IllegalArgumentException - ヘッダーの名前または値が有効でない場合、「RFC 7230セクション-3.2」を参照するか、ヘッダーの名前または値が実装によって制限されます。

headers

HttpRequest.Builder headers(String... headers)

指定された名前と値のペアを、このリクエストのヘッダーのセットに追加します。 提供されたStringインスタンスは、ヘッダー名とヘッダー値として代替する必要があります。 同じ名前に複数の値を追加するには、新しい名前ごとに同じ名前を指定する必要があります。

パラメータ:

headers - 名前値のペアのリスト

戻り値:

このビルダー

例外:

IllegalArgumentException - 奇数のパラメータがある場合、またはヘッダーの名前または値が有効でない場合は、実装によって「RFC 7230セクション-3.2」またはヘッダーの名前または値が「制限付き」になります。

timeout

HttpRequest.Builder timeout(Duration duration)

このリクエストのタイムアウトを設定します。 指定されたタイムアウト内にレスポンスを受信しなかった場合、HttpClient::sendまたはHttpClient::sendAsyncからHttpTimeoutExceptionが例外的にHttpTimeoutExceptionを使ってスローされます。 タイムアウトを設定しない場合の影響は、無限期間(永続的ブロック)の設定と同じです。

パラメータ:

duration - タイムアウト期間

戻り値:

このビルダー

例外:

IllegalArgumentException - 期間が非正の場合

setHeader

HttpRequest.Builder setHeader(String name, String value)

指定された名前値ペアを、このリクエストのヘッダーのセットに設定します。 これにより、以前に設定された名前の値が上書きされます。

パラメータ:

name - ヘッダー名

value - ヘッダー値

戻り値:

このビルダー

例外:

IllegalArgumentException - ヘッダーの名前または値が有効でない場合、実装によって「RFC 7230セクション-3.2」を参照するか、ヘッダー名または値が「制限付き」です。

GET

HttpRequest.Builder GET()

このビルダーのリクエスト・メソッドをGETに設定します。 これはデフォルトです。

戻り値:

このビルダー

POST

HttpRequest.Builder POST(HttpRequest.BodyPublisher bodyPublisher)

このBuilderのリクエスト・メソッドをPOSTに設定し、リクエスト本文パブリッシャを指定された値に設定します。

パラメータ:

bodyPublisher - 本文パブリッシャ

戻り値:

このビルダー

PUT

HttpRequest.Builder PUT(HttpRequest.BodyPublisher bodyPublisher)

このBuilderのリクエスト・メソッドをPUTに設定し、リクエスト本文パブリッシャを指定された値に設定します。

パラメータ:

bodyPublisher - 本文パブリッシャ

戻り値:

このビルダー

DELETE

HttpRequest.Builder DELETE()

このビルダーのリクエスト・メソッドをDELETEに設定します。

戻り値:

このビルダー

HEAD

default HttpRequest.Builder HEAD()

このビルダーのリクエスト・メソッドをHEADに設定します。

実装要件:

デフォルトの実装の動作は、次のようになります: return method("HEAD", BodyPublishers.noBody());

戻り値:

このビルダー

導入されたバージョン:

18

method

HttpRequest.Builder method(String method, HttpRequest.BodyPublisher bodyPublisher)

このビルダーのリクエスト・メソッドおよびリクエスト本文を指定された値に設定します。

APIのノート:

noBodyリクエスト本文パブリッシャは、リクエスト本文が必要ない場合や適切でない場合に使用できます。 メソッドが制限されるかどうかは、実装に固有です。 たとえば、一部の実装では、CONNECTメソッドを制限するよう選択できます。

パラメータ:

method - 使用するメソッド

bodyPublisher - 本文パブリッシャ

戻り値:

このビルダー

例外:

IllegalArgumentException - メソッド名が有効でない場合、「RFC 7230セクション-3.1.1」を参照するか、メソッドが実装によって制限されます。

build

HttpRequest build()

HttpRequestを作成して返します。

実装要件:

このメソッドは、起動されるたびに新しいHttpRequestを返します。 作成後、HttpRequestは変更できず、複数回送信できます。

戻り値:

新しいHttpRequest

例外:

IllegalStateException - URIが設定されていない場合

copy

HttpRequest.Builder copy()

現在の状態に基づいて、このBuilderの正確な複製コピーを返します。 新しいビルダーは、このビルダーから独立して変更できます。

戻り値:

このビルダーの正確なコピー