モジュール java.net.http

パッケージ java.net.http

インタフェースHttpClient.Builder

含まれているクラス:

HttpClient

public static interface HttpClient.Builder

「HTTPクライアント」のビルダー。

ビルダーは、newBuilderを呼び出すことによって作成されます。 各setterメソッドは、Builderの状態を変更し、同じインスタンスを返します。 ビルダーはスレッド・セーフではないため、外部同期なしで複数のスレッドから同時に使用すべきではありません。

導入されたバージョン:

11

フィールドのサマリー

フィールド

修飾子と型	フィールド	説明
static final ProxySelector	NO_PROXY	直接接続を意味するProxy.NO_PROXYを常に返すプロキシ・セレクタ。

メソッドのサマリー

修飾子と型	メソッド	説明
HttpClient.Builder	authenticator(Authenticator authenticator)	HTTP認証に使用するオーセンティケータを設定します。
HttpClient	build()	このビルダーの現在の状態から構築された新しいHttpClientを返します。
HttpClient.Builder	connectTimeout(Duration duration)	このクライアントの接続タイムアウト期間を設定します。
HttpClient.Builder	cookieHandler(CookieHandler cookieHandler)	cookieハンドラを設定します。
HttpClient.Builder	executor(Executor executor)	非同期および依存タスクに使用されるエグゼキュータを設定します。
HttpClient.Builder	followRedirects(HttpClient.Redirect policy)	リクエストが、サーバーによって発行されたリダイレクトを自動的に追跡するかどうかを指定します。
default HttpClient.Builder	localAddress(InetAddress localAddr)	リクエストを送信するための接続を作成するときに、ソケットをこのローカル・アドレスにバインドします。
HttpClient.Builder	priority(int priority)	このクライアントから送信されたHTTP/2リクエストのデフォルトの優先順位を設定します。
HttpClient.Builder	proxy(ProxySelector proxySelector)	ProxySelectorを設定します。
HttpClient.Builder	sslContext(SSLContext sslContext)	SSLContextを設定します。
HttpClient.Builder	sslParameters(SSLParameters sslParameters)	SSLParametersを設定します。
HttpClient.Builder	version(HttpClient.Version version)	可能な場合は、特定のHTTPプロトコル・バージョンをリクエストします。

フィールド詳細

NO_PROXY

static final ProxySelector NO_PROXY

直接接続を意味するProxy.NO_PROXYを常に返すプロキシ・セレクタ。

これは、プロキシを使用しないHttpClientのインスタンスを作成するためにproxy(ProxySelector)に渡すことができる便利なオブジェクトです。

メソッドの詳細

cookieHandler

HttpClient.Builder cookieHandler(CookieHandler cookieHandler)

cookieハンドラを設定します。

パラメータ:

cookieHandler - cookieハンドラ

戻り値:

このビルダー

connectTimeout

HttpClient.Builder connectTimeout(Duration duration)

このクライアントの接続タイムアウト期間を設定します。

新しい接続を確立する必要がある場合に、指定された duration内に接続を確立できないと、HttpClient::sendはHttpConnectTimeoutExceptionをスローし、HttpClient::sendAsyncはHttpConnectTimeoutExceptionを使用して例外的に完了します。 たとえば、接続を前のリクエストから再利用できる場合など、新しい接続を確立する必要がない場合、このタイムアウト期間は影響しません。

パラメータ:

duration - 基礎となる接続の確立を許可する期間

戻り値:

このビルダー

例外:

IllegalArgumentException - 期間が非正の場合

sslContext

HttpClient.Builder sslContext(SSLContext sslContext)

SSLContextを設定します。

このメソッドがbuildingの前に呼び出されない場合、新しく構築されたクライアントは「デフォルト・コンテキスト」を使用します。これは通常、プロトコルを指定する必要がない、またはクライアント認証を必要とするクライアント・アプリケーションに適しています。

パラメータ:

sslContext - the SSLContext

戻り値:

このビルダー

sslParameters

HttpClient.Builder sslParameters(SSLParameters sslParameters)

SSLParametersを設定します。

このメソッドがbuildingの前に呼び出されない場合、新しく構築されたクライアントはデフォルトの実装固有のパラメータ・セットを使用します。

HTTPクライアント実装(アプリケーション・プロトコル・リスト)によって内部的に使用されるいくつかのパラメータは、無視される可能性があるため、呼び出し元によって設定されるべきではありません。 指定されたオブジェクトの内容がコピーされます。

パラメータ:

sslParameters - the SSLParameters

戻り値:

このビルダー

executor

HttpClient.Builder executor(Executor executor)

非同期および依存タスクに使用されるエグゼキュータを設定します。

このメソッドがbuildingの前に呼び出されない場合、新しく作成された HttpClientごとにデフォルトのエグゼキュータが作成されます。

実装上のノート:

デフォルト・エグゼキュータでは、カスタム・スレッド・ファクトリを備えたスレッド・プールが使用されます。 セキュリティ・マネージャがインストールされている場合、スレッド・ファクトリは、アクセス権を持たないアクセス制御コンテキストで実行されるスレッドを作成します。

パラメータ:

executor - エグゼクティブ

戻り値:

このビルダー

followRedirects

HttpClient.Builder followRedirects(HttpClient.Redirect policy)

リクエストが、サーバーによって発行されたリダイレクトを自動的に追跡するかどうかを指定します。

このメソッドがbuildingの前に呼び出されない場合、新しく構築されたクライアントはNEVERのデフォルトのリダイレクション・ポリシーを使用します。

パラメータ:

policy - リダイレクト・ポリシー

戻り値:

このビルダー

version

HttpClient.Builder version(HttpClient.Version version)

可能な場合は、特定のHTTPプロトコル・バージョンをリクエストします。

このメソッドがbuildingの前に呼び出されない場合、新しく構築されたクライアントはHTTP/2を優先します。

HTTP/2に設定すると、各リクエストはHTTP/2へのアップグレードを試みます。 アップグレードが成功すると、このリクエストに対するレスポンスはHTTP/2を使用し、その後のすべてのリクエストと同じ「オリジン・サーバー」へのレスポンスはHTTP/2を使用します。 アップグレードに失敗すると、レスポンスはHTTP/1.1を使用して処理されます

実装上のノート:

制約は、プロトコル・バージョンの選択に影響する場合もあります。 たとえば、プロキシを介してHTTP/2がリクエストされ、実装がこのモードをサポートしない場合、HTTP/1.1を使用できます。

パラメータ:

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

戻り値:

このビルダー

priority

HttpClient.Builder priority(int priority)

このクライアントから送信されたHTTP/2リクエストのデフォルトの優先順位を設定します。 指定する値は、1と256 (inclusive)の間にある必要があります。

パラメータ:

priority - 優先度の重み付け

戻り値:

このビルダー

例外:

IllegalArgumentException - 指定された優先度が範囲外の場合

proxy

HttpClient.Builder proxy(ProxySelector proxySelector)

ProxySelectorを設定します。

APIのノート:

ProxySelector::ofは、すべてのリクエストに対して単一のプロキシを使用するProxySelectorを提供します。 システム全体のプロキシ・セレクタは、ProxySelector.getDefault()で取得できます。

実装上のノート:

このメソッドがbuildingの前に起動されない場合、新しく作成されたクライアントは「デフォルト・プロキシ・セレクタ」を使用しますが、これは通常クライアント・アプリケーションに適しています。 デフォルトのプロキシ・セレクタは「プロキシ設定」に関連するシステム・プロパティのセットをサポートします。 NO_PROXYや、ProxySelector::ofによって返される明示的なプロキシ・セレクタを指定して、buildingの前にこのデフォルト動作を無効にすることができます。

パラメータ:

proxySelector - the ProxySelector

戻り値:

このビルダー

authenticator

HttpClient.Builder authenticator(Authenticator authenticator)

HTTP認証に使用するオーセンティケータを設定します。

パラメータ:

authenticator - オーセンティケータ

戻り値:

このビルダー

localAddress

default HttpClient.Builder localAddress(InetAddress localAddr)

リクエストを送信するための接続を作成するときに、ソケットをこのローカル・アドレスにバインドします。

ローカル・アドレスが設定されていない場合、またはnullがこのメソッドに渡された場合、HTTPクライアントによって作成されたソケットは自動的に割り当てられたソケット・アドレスにバインドされます。

HttpClientの一般的な使用方法では、このメソッドをコールする必要はありません。 このメソッドを使用してローカル・アドレスを設定するのは、HttpClientのユーザーがHTTP通信に使用するネットワーク・インタフェースを特定の制御する必要がある高度な使用方法のみです。 このメソッドのコール元は、HttpClientが使用されるシステムのネットワーク構成を認識し、正しいlocalAddrが渡されるように注意する必要があります。 そうしないと、HttpClientを介して送信されたリクエストが失敗する可能性があります。

実装要件:

このメソッドのデフォルト実装はUnsupportedOperationExceptionをスローします。 HttpClient.newBuilder()を介して取得されるBuilderは、ローカル・アドレスの設定を可能にするこのメソッドの実装を提供します。

パラメータ:

localAddr - ソケットのローカル・アドレス。 nullも可。

戻り値:

このビルダー

例外:

UnsupportedOperationException - このビルダーがローカル・アドレスの構成をサポートしていない場合、または渡されたlocalAddrがこのHttpClient実装でサポートされていない場合。

導入されたバージョン:

19

build

HttpClient build()

このビルダーの現在の状態から構築された新しいHttpClientを返します。

実装要件:

local addressがnull以外のアドレスで、セキュリティ・マネージャがインストールされている場合、このメソッドはcheckListenをコールして、コール元がそのローカル・アドレスにバインドするために必要な権限を持っていることを確認します。

戻り値:

新しいHttpClient

例外:

UncheckedIOException - 実装に必要な基礎となるIOリソースを割り当てることができない場合にスローされることがあります。 たとえば、実装にSelectorが必要で、「必要なリソースの不足」が原因でオープンに失敗した場合です。

SecurityException - セキュリティ・マネージャがインストールされていて、セキュリティ・マネージャのcheckListenメソッドが指定されたアドレスへのバインドを許可しない場合。