モジュール java.net.http
パッケージ java.net.http

クラス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);

セキュリティ・チェック

セキュリティ・マネージャが存在する場合は、HTTPクライアントの送信メソッドによってセキュリティ・チェックが実行されます。 宛先サーバーにアクセスするには適切なURLPermissionが必要で、プロキシ・サーバーが構成されている場合はプロキシ・サーバーにアクセスする必要があります。 プロキシにアクセスするために必要なURLPermissionの形式には、"CONNECT" (すべての種類のプロキシ処理)のmethodパラメータと、フォーム"socket://host:port"のURL文字列があり、ホストとポートでプロキシ・アドレスを指定します。

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

HttpClientのJDK組込み実装は、ベスト・エフォート実装を提供するために、close()、shutdown()、shutdownNow()、awaitTermination(Duration)およびisTerminated()をオーバーライドします。 HttpResponse.BodyHandlers.ofInputStream()、HttpResponse.BodyHandlers.ofLines()、またはHttpResponse.BodyHandlers.ofPublisher()を使用するときに提供されるストリームなど、返されたストリームを閉じる、取り消す、または読み取ることができないと、「正常停止」を実行する前に送信されたリクエストが完了するまで実行できないことがあります。 同様に、カスタムBodySubscriberから「リクエスト・データ」または「サブスクリプションを解約」に失敗すると、データおよび「正常な停止を停止」の配信が停止する可能性があります。

executorがHttpClientに明示的に設定されておらず、セキュリティ・マネージャがインストールされている場合、デフォルト・エグゼキュータは権限が付与されていないコンテキストで非同期タスクおよび依存タスクを実行します。 カスタムの「本文パブリッシャをリクエスト」、「レスポンス本文ハンドラ」、「レスポンス本文サブスクライバ」および「WebSocketリスナー」は、権限が必要な操作を実行する場合は、適切な「特権的なコンテキスト」内で実行する必要があります。

導入されたバージョン:
11

  • コンストラクタの詳細

    • 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で指定された有効に作成されたリクエストではない場合。
      SecurityException - セキュリティ・マネージャがインストールされていて、指定されたリクエストのURLにaccessを拒否した場合、またはプロキシが構成されている場合はプロキシを拒否します。 詳細は、「セキュリティ・チェック」を参照してください。

    • 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エラーが発生した場合、またはクライアントに「停止」がある場合。
      • SecurityException - セキュリティ・マネージャがインストールされていて、指定されたリクエストのURLにaccessを拒否した場合、またはプロキシが構成されている場合はプロキシを拒否します。 詳細は、「セキュリティ・チェック」を参照してください。

      デフォルトの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
      関連項目:

    • awaitTermination

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

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

      実装要件:
      このメソッドのデフォルトの実装ではnull引数がチェックされますが、それ以外の場合は何もチェックされず、trueが返されます。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。
      パラメータ:
      duration - 最大待機時間
      戻り値:
      このクライアントが終了した場合はtrue、終了前にタイムアウトが経過した場合はfalse
      例外:
      InterruptedException - 待機中に割込みが発生した場合
      導入されたバージョン:
      21
      関連項目:

    • isTerminated

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

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

      実装要件:
      このメソッドのデフォルトの実装では何も実行されず、falseが返されます。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。
      戻り値:
      停止後にすべてのタスクが完了した場合はtrue
      導入されたバージョン:
      21
      関連項目:

    • shutdownNow

      public void shutdownNow()
      このメソッドは、即時シャットダウンを開始しようとします。 このメソッドの実装は、アクティブに実行されている操作を中断しようとする場合があります。 操作は、sendまたはsendAsyncで以前に送信されたリクエストを完了まで実行するために必要なタスクです。 中断時のアクティブに実行されている操作の動作は未定義です。 特に、中断された操作が終了すること、またはこれらの操作を待機しているコードに通知される保証はありません。
      実装要件:
      このメソッドのデフォルトの実装では、単にshutdown()をコールします。 サブクラスは、適切な動作を実装するためにこのメソッドをオーバーライドする必要があります。
      導入されたバージョン:
      21
      関連項目:

    • close

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

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

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

      定義:
      close、インタフェースAutoCloseable
      実装要件:
      デフォルトの実装では、shutdown()が起動され、タスクがawaitTerminationを使用して実行を完了するまで待機します。
      導入されたバージョン:
      21
      関連項目: