クラスHttpClient

java.lang.Object

java.net.http.HttpClient

すべての実装されたインタフェース:

AutoCloseable

public abstract class HttpClient extends Object implements AutoCloseable

HTTPクライアント。

HttpClientを使用して「リクエスト」を送信し、「レスポンス」を取得できます。 builderを介して HttpClientが作成されます。 newBuilderメソッドは、デフォルトのHttpClient実装のインスタンスを作成するビルダーを返します。 ビルダーを使用して、クライアントごとに次のような状態を構成できます: 優先プロトコル・バージョン(HTTP/1.1またはHTTP/2)、リダイレクトの有無、プロキシ、認証プロバイダなどがあります。一度ビルドされると、HttpClientは不変になり、複数のリクエストの送信に使用できます。

HttpClientは、すべてのリクエストの構成情報とリソース共有を提供します。 HttpClientインスタンスは、通常、独自の接続プールを管理します。その後、必要に応じて再利用できます。 通常、接続プールはHttpClientインスタンス間で共有されません。 可能なかぎり、操作ごとに新しいクライアントを作成すると、通常、そのような接続の再利用が防止されます。

HttpRequestが送信されるたびにBodyHandlerを指定する必要があります。 BodyHandlerは、レスポンス本文(存在する場合)の処理方法を決定します。 HttpResponseを受信すると、ヘッダー、レスポンス・コードおよび本文(typically)を使用できます。 レスポンス本文のバイトが読み取られたかどうかは、レスポンス本文のタイプ(T)によって決まります。

リクエストは同期または非同期のいずれかで送信できます。

• send(HttpRequest, BodyHandler)ブロックは、リクエストが送信されてレスポンスが受信されるまでブロックされます。
• sendAsync(HttpRequest, BodyHandler)がリクエストを送信し、レスポンスを非同期に受信します。 sendAsyncメソッドは、すぐにCompletableFuture<HttpResponse>を返します。 レスポンスが使用可能になると、 CompletableFutureが完了します。 返されたCompletableFutureは、様々な方法で結合して複数の非同期タスク間の依存性を宣言できます。

同期の例

HttpClient client = HttpClient.newBuilder()
     .version(Version.HTTP_1_1)
     .followRedirects(Redirect.NORMAL)
     .connectTimeout(Duration.ofSeconds(20))
     .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
     .authenticator(Authenticator.getDefault())
     .build();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

非同期の例

 HttpRequest request = HttpRequest.newBuilder()
     .uri(URI.create("https://foo.com/"))
     .timeout(Duration.ofMinutes(2))
     .header("Content-Type", "application/json")
     .POST(BodyPublishers.ofFile(Paths.get("file.json")))
     .build();
client.sendAsync(request, BodyHandlers.ofString())
     .thenApply(HttpResponse::body)
     .thenAccept(System.out::println);

APIのノート:

HttpClientによって割り当てられたリソースは、クライアント「閉じる」によって早期に再利用できます。

実装上のノート:

HttpResponse.BodyHandlersクラスとHttpResponse.BodySubscribersクラスには、本文データをコール元にストリームして戻すことができる「BodyHandlerおよびBodySubscriber実装のストリーミングまたは公開」が用意されています。 これらのストリームに関連付けられたリソースを再利用し、HTTPリクエストが完了したとみなすには、コール元が最終的に「ストリーミング・レスポンス本文の取得」を実行して、返されたストリームを閉じるか、取り消すか、読み取る必要があります。 同様に、カスタムのHttpResponse.BodySubscriber実装では、onCompleteまたはonErrorがシグナルを受信するまで、すべてのデータをrequestするか、最終的にそのサブスクリプションをcancelする必要があります。

HttpClientのJDK組込み実装は、ベスト・エフォート実装を提供するために、close()、shutdown()、shutdownNow()、awaitTermination(Duration)およびisTerminated()をオーバーライドします。 streaming or publishing bodiesのクローズ、取消または読取りに失敗すると、リクエストを開いたままにし、「正常な停止を停止」でデータの配信が停止する場合があります。 shutdownNow()メソッド(コールされた場合)は、このような未完了のリクエストを取り消そうとしますが、操作の実行時に突然終了する場合があります。

「明示的に閉じました」でない場合、HttpClientインスタンスが強く到達できなくなり、そのインスタンスで起動されたすべての操作が完了すると、HttpClientのJDK組込み実装によってそのリソースが解放されます。 これは、ガベージ・コレクタの両方に依存して、インスタンスがアクセスできなくなったこと、およびクライアントで起動されたすべてのリクエストで最終的に完了することを通知します。 「ストリーミングまたはパブリッシュ・ボディ」を適切にクローズしないと、関連するリクエストの実行から完了までが妨げられ、関連付けられたクライアントによって割り当てられたリソースがガベージ・コレクタによって再利用されない場合があります。

導入されたバージョン:

11

ネストされたクラスのサマリー

ネストされたクラス

修飾子と型	クラス	説明
static interface	HttpClient.Builder	「HTTPクライアント」のビルダー。
static enum	HttpClient.Redirect	自動リダイレクション・ポリシーを定義します。
static enum	HttpClient.Version	HTTPプロトコルのバージョン。

コンストラクタのサマリー

コンストラクタ

修飾子	コンストラクタ	説明
protected	HttpClient()	HttpClientを作成します。

メソッドのサマリー

修飾子と型	メソッド	説明
abstract Optional<Authenticator>	authenticator()	このクライアントに設定されたAuthenticatorを含むOptionalを返します。
boolean	awaitTermination(Duration duration)	シャットダウン・リクエストの後にすべての操作の実行が完了するか、durationが経過するか、現在のスレッドがinterrupted(いずれか早い方)になるまでブロックします。
void	close()	以前にsendまたはsendAsyncに送信されたリクエストが完了するまで実行されるが、新しいリクエストは受け入れられないように、正常な停止を開始します。
abstract Optional<Duration>	connectTimeout()	このクライアントの「接続タイムアウト時間」を含むOptionalを返します。
abstract Optional<CookieHandler>	cookieHandler()	このクライアントCookieHandlerを含むOptionalを返します。
abstract Optional<Executor>	executor()	このクライアントExecutorを含むOptionalを返します。
abstract HttpClient.Redirect	followRedirects()	このクライアントのフォロー・リダイレクト・ポリシーを返します。
boolean	isTerminated()	停止後にすべての操作が完了した場合は、trueを返します。
static HttpClient.Builder	newBuilder()	新しいHttpClientビルダーを作成します。
static HttpClient	newHttpClient()	デフォルト設定を使用して新しいHttpClientを返します。
WebSocket.Builder	newWebSocketBuilder()	新しいWebSocketビルダー(オプションの操作)を作成します。
abstract Optional<ProxySelector>	proxy()	このクライアントに提供されたProxySelectorを含むOptionalを返します。
abstract <T> HttpResponse<T>	send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)	このクライアントを使用して指定されたリクエストを送信し、必要に応じてブロックしてレスポンスを取得します。
abstract <T> CompletableFuture<HttpResponse<T>>	sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)	指定されたレスポンス本文ハンドラとともに、このクライアントを使用して、指定されたリクエストを非同期に送信します。
abstract <T> CompletableFuture<HttpResponse<T>>	sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler, HttpResponse.PushPromiseHandler<T> pushPromiseHandler)	指定されたレスポンス本文ハンドラとともにこのクライアントを使用して、指定されたリクエストを非同期に送信し、プッシュ・プロミス・ハンドラをプッシュします。
void	shutdown()	sendまたはsendAsyncで以前に送信されたリクエストが完了まで実行され、新しいリクエストは受け入れられないように、正常な停止を開始します。
void	shutdownNow()	このメソッドは、即時シャットダウンを開始しようとします。
abstract SSLContext	sslContext()	このクライアントのSSLContextを返します。
abstract SSLParameters	sslParameters()	このクライアントのSSLParametersのコピーを返します。
abstract HttpClient.Version	version()	このクライアントの優先HTTPプロトコル・バージョンを返します。

クラスjava.lang.Objectで宣言されたメソッド

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

コンストラクタの詳細

HttpClient

protected HttpClient()

HttpClientを作成します。

メソッドの詳細

newHttpClient

public static HttpClient newHttpClient()

デフォルト設定を使用して新しいHttpClientを返します。

newBuilder().build()と等価です。

デフォルト設定には: "GET"リクエスト・メソッド、HTTP/2のプリファレンス、NEVERのリダイレクション・ポリシー、「デフォルト・プロキシ・セレクタ」および「デフォルトのSSLコンテキスト」。

実装上のノート:

システム全体のデフォルト値は、HttpClientインスタンスの構築時に取得されます。 たとえば、ProxySelector.setDefault(ProxySelector)またはSSLContext.setDefault(SSLContext)をコールして、HttpClientインスタンスのビルド後にシステム全体の値を変更しても、すでにビルドされているインスタンスには影響しません。

戻り値:

新しいHttpClient

スロー:

UncheckedIOException - 「新しいHttpClientの構築」に必要な基礎となるIOリソースを割り当てることができない場合。

newBuilder

public static HttpClient.Builder newBuilder()

新しいHttpClientビルダーを作成します。

このメソッドによって返されるビルダーは、デフォルトのHttpClient実装のインスタンスを作成します。

戻り値:

an HttpClient.Builder

cookieHandler

public abstract Optional<CookieHandler> cookieHandler()

このクライアントCookieHandlerを含むOptionalを返します。 このクライアントのビルダーでCookieHandlerが設定されていない場合、Optionalは空です。

戻り値:

このクライアントのCookieHandlerを含むOptional

connectTimeout

public abstract Optional<Duration> connectTimeout()

このクライアントの「接続タイムアウト時間」を含むOptionalを返します。 クライアント・ビルダーで「接続タイムアウト時間」が設定されていない場合、Optionalは空になります。

戻り値:

このクライアント接続のタイムアウト時間を含むOptional

followRedirects

public abstract HttpClient.Redirect followRedirects()

このクライアントのフォロー・リダイレクト・ポリシーを返します。 リダイレクト・ポリシーを指定しないビルダーによって構築されるクライアントのデフォルト値は、NEVERです。

戻り値:

このクライアントのフォロー・リダイレクト設定

proxy

public abstract Optional<ProxySelector> proxy()

このクライアントに提供されたProxySelectorを含むOptionalを返します。 このクライアントのビルダーでプロキシ・セレクタが設定されていない場合、Optionalは空です。

このメソッドが空のオプションを返すこともありますが、HTTPリクエストの送信に使用される、 HttpClientには突然の「デフォルト・プロキシ・セレクタ」がある可能性があります。

戻り値:

このクライアントに提供されたプロキシ・セレクタを含むOptional。

sslContext

public abstract SSLContext sslContext()

このクライアントのSSLContextを返します。

このクライアントのビルダーでSSLContextが設定されていない場合は、「デフォルト・コンテキスト」が返されます。

戻り値:

このクライアントのSSLContext

sslParameters

public abstract SSLParameters sslParameters()

このクライアントのSSLParametersのコピーを返します。

クライアントのビルダーでSSLParametersが設定されていない場合は、実装固有のデフォルトのパラメータ・セット(クライアントが使用するパラメータ)が返されます。

戻り値:

このクライアントのSSLParameters

authenticator

public abstract Optional<Authenticator> authenticator()

このクライアントに設定されたAuthenticatorを含むOptionalを返します。 クライアントのビルダーでAuthenticatorが設定されていない場合、Optionalは空です。

戻り値:

このクライアントのAuthenticatorを含むOptional

version

public abstract HttpClient.Version version()

このクライアントの優先HTTPプロトコル・バージョンを返します。 デフォルト値はHttpClient.Version.HTTP_2です。

実装上のノート:

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

戻り値:

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

executor

public abstract Optional<Executor> executor()

このクライアントExecutorを含むOptionalを返します。 クライアントのビルダーでExecutorが設定されていない場合、Optionalは空です。

このメソッドは空のオプションを返すかもしれませんが、 HttpClientには、非同期および依存タスクの実行に使用される「デフォルトのエグゼキュータ」がまだ公開されていないことがあります。

戻り値:

このクライアントのExecutorを含むOptional

send

public abstract <T> HttpResponse<T> send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler) throws IOException, InterruptedException

このクライアントを使用して指定されたリクエストを送信し、必要に応じてブロックしてレスポンスを取得します。 返されたHttpResponse<T>には、レスポンス・ステータス、ヘッダーおよび本文(指定されたレスポンス本文ハンドラによって処理される)が含まれます。

演算が中断された場合、デフォルトのHttpClient実装はHTTP交換を取り消そうとし、InterruptedExceptionがスローされます。 whenに関する正確な保証はありません。取消リクエストが考慮される可能性があります。 特に、リクエストの処理が別のスレッドですでに非同期的に開始されており、基礎となるリソースが非同期的にのみ解放される可能性があるため、リクエストがサーバーに送信される場合があります。

• HTTP/1.1では、取り消そうとすると、基礎となる接続が突然閉じられる可能性があります。
• HTTP/2では、取消しを試みると、ストリームがリセットされたり、特定の状況では、スレッドが基礎となるソケットに現在書き込もうとしている場合に、接続が突然クローズされることもあります。

型パラメータ:

T - レスポンス本文型

パラメータ:

request - リクエスト

responseBodyHandler - レスポンス本文ハンドラ

戻り値:

レスポンス

スロー:

IOException - 送信または受信時にI/Oエラーが発生した場合、またはクライアントに「停止」がある場合

InterruptedException - 操作が中断された場合

IllegalArgumentException - request引数がHttpRequest.Builderで指定された有効に作成されたリクエストではない場合。

sendAsync

public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)

指定されたレスポンス本文ハンドラとともに、このクライアントを使用して、指定されたリクエストを非同期に送信します。

同等: sendAsync(request, responseBodyHandler, null)。

型パラメータ:

T - レスポンス本文型

パラメータ:

request - リクエスト

responseBodyHandler - レスポンス本文ハンドラ

戻り値:

a CompletableFuture<HttpResponse<T>>

スロー:

IllegalArgumentException - request引数がHttpRequest.Builderで指定された有効に作成されたリクエストではない場合。

sendAsync

public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler, HttpResponse.PushPromiseHandler<T> pushPromiseHandler)

指定されたレスポンス本文ハンドラとともにこのクライアントを使用して、指定されたリクエストを非同期に送信し、プッシュ・プロミス・ハンドラをプッシュします。

戻されたcompletableは、将来正常に完了すると、レスポンス・ステータス、ヘッダーおよび本文(指定されたレスポンス本文ハンドラによって処理される)を含むHttpResponse<T>で完了します。

「プッシュ・プロミス」がある場合は、所定のpushPromiseHandlerによって処理されます。 null値がpushPromiseHandlerである場合、プッシュ・プロミスは拒否されます。

返された完了可能な未来は例外的に次のように完了します:

• IOException - 送信または受信時にI/Oエラーが発生した場合、またはクライアントに「停止」がある場合。

デフォルトのHttpClient実装は、cancelableであるCompletableFutureオブジェクトを返します。 取消可能な先日付からのCompletableFutureオブジェクトderivedは、それ自体がcancelableです。 完了していない取消し可能な将来、cancel(true)を起動すると、基礎となるリソースをできるだけ早く解放するためにHTTP交換の取消しが試行されます。 whenに関する正確な保証はありません。取消リクエストが考慮される可能性があります。 特に、リクエストの処理が別のスレッドですでに非同期的に開始されており、基礎となるリソースが非同期的にのみ解放される可能性があるため、リクエストがサーバーに送信される場合があります。

• HTTP/1.1では、取り消そうとすると、基礎となる接続が突然閉じられる可能性があります。
• HTTP/2では、取り消そうとするとストリームがリセットされることがあります。

型パラメータ:

T - レスポンス本文型

パラメータ:

request - リクエスト

responseBodyHandler - レスポンス本文ハンドラ

pushPromiseHandler - プッシュ・プロミス・ハンドラ。nullの可能性があります。

戻り値:

a CompletableFuture<HttpResponse<T>>

スロー:

IllegalArgumentException - request引数がHttpRequest.Builderで指定された有効に作成されたリクエストではない場合。

newWebSocketBuilder

public WebSocket.Builder newWebSocketBuilder()

新しいWebSocketビルダー(オプションの操作)を作成します。

例

HttpClient client = HttpClient.newHttpClient();
CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
   .buildAsync(URI.create("ws://websocket.example.com"), listener);

カスタムのHttpClientを使用すると、WebSocketオープニング・ハンドシェイクの細かい制御が可能になります。

例

InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
HttpClient client = HttpClient.newBuilder()
        .proxy(ProxySelector.of(addr))
        .build();

CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
        .buildAsync(URI.create("ws://websocket.example.com"), listener);

実装要件:

このメソッドのデフォルト実装はUnsupportedOperationExceptionをスローします。 newHttpClient()またはnewBuilder()で取得したクライアントは、WebSocket Builderを返します。

実装上のノート:

ビルダーとそれで作成されたWebSocketの両方が、非ブロッキングの方法で動作します。 つまり、それらのメソッドはCompletableFutureを返す前にブロックしません。 非同期タスクは、このHttpClientのエグゼキュータで実行されます。

CompletionStageがListener.onCloseから返されると、WebSocketは、受信したメッセージと同じコードを持ち、空の理由があるCloseメッセージを送信します。

戻り値:

a WebSocket.Builder

スロー:

UnsupportedOperationException - このHttpClientがWebSocketサポートを提供しない場合

shutdown

public void shutdown()

sendまたはsendAsyncで以前に送信されたリクエストが完了まで実行され、新しいリクエストは受け入れられないように、正常な停止を開始します。 完了までのリクエストの実行には、バックグラウンドで複数の操作(「レスポンスの配信待機中」など)の実行が含まれる場合があります。この操作はすべて、リクエストが完了したと見なされるまで完了まで実行する必要があります。 シャットダウン後に呼出しを実行しても、効果はありません。

このメソッドは、以前に発行されたリクエストの実行が完了するまで待機しません。 これを行うには、awaitTerminationまたはcloseを使用します。

実装要件:

このメソッドのデフォルト実装では何の処理も行われません。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。

導入されたバージョン:

21

関連項目:

• HttpClientのクローズに関する実装に関するノート

awaitTermination

public boolean awaitTermination(Duration duration) throws InterruptedException

シャットダウン・リクエストの後にすべての操作の実行が完了するか、durationが経過するか、現在のスレッドがinterrupted(いずれか早い方)になるまでブロックします。 操作は、sendまたはsendAsyncで以前に送信されたリクエストを完了まで実行するために必要なタスクです。

このメソッドは、待機期間がゼロ以下の場合は待機しません。 この場合、メソッドはスレッドが終了しているかどうかのみをテストします。

実装要件:

このメソッドのデフォルトの実装ではnull引数がチェックされますが、それ以外の場合は何もチェックされず、trueが返されます。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。

パラメータ:

duration - 最大待機時間

戻り値:

このクライアントが終了した場合はtrue、終了前にタイムアウトが経過した場合はfalse

スロー:

InterruptedException - 待機中に割込みが発生した場合

導入されたバージョン:

21

関連項目:

• HttpClientのクローズに関する実装に関するノート

isTerminated

public boolean isTerminated()

停止後にすべての操作が完了した場合は、trueを返します。 操作は、sendまたはsendAsyncで以前に送信されたリクエストを完了まで実行するために必要なタスクです。

shutdownまたはshutdownNowのいずれかが最初に呼び出された場合を除き、isTerminatedがtrueになることはありません。

実装要件:

このメソッドのデフォルトの実装では何も実行されず、falseが返されます。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。

戻り値:

停止後にすべてのタスクが完了した場合はtrue

導入されたバージョン:

21

関連項目:

• HttpClientのクローズに関する実装に関するノート

shutdownNow

public void shutdownNow()

このメソッドは、即時シャットダウンを開始しようとします。 このメソッドの実装は、アクティブに実行されている操作を中断しようとする場合があります。 操作は、sendまたはsendAsyncで以前に送信されたリクエストを完了まで実行するために必要なタスクです。 中断時のアクティブに実行されている操作の動作は未定義です。 特に、中断された操作が終了すること、またはこれらの操作を待機しているコードに通知される保証はありません。

実装要件:

このメソッドのデフォルトの実装では、単にshutdown()をコールします。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。

導入されたバージョン:

21

関連項目:

• HttpClientのクローズに関する実装に関するノート

close

public void close()

以前にsendまたはsendAsyncに送信されたリクエストが完了するまで実行されるが、新しいリクエストは受け入れられないように、正常な停止を開始します。 完了へのリクエストの実行には、「レスポンスの配信待機中」など、バックグラウンドでの複数の操作の実行が含まれる場合があります。 このメソッドは、すべての操作の実行が完了してクライアントが終了するまで待機します。

待機中に中断された場合、このメソッドはshutdownNow()をコールしてすべての操作を停止しようとします。 その後、アクティブに実行されているすべての操作が完了するまで待機し続けます。 割り込みステータスは、このメソッドが戻る前に再アサートされます。

すでに終了している場合は、このメソッドを呼び出しても効果はありません。

定義:

close、インタフェースAutoCloseable

実装要件:

デフォルトの実装では、shutdown()が起動され、タスクがawaitTerminationを使用して実行を完了するまで待機します。

導入されたバージョン:

21

関連項目:

• HttpClientのクローズに関する実装に関するノート