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

クラスHttpClient

  • public abstract class HttpClient
extends Object
    HTTPクライアント。

    HttpClientを使用して「リクエスト」を送信し、「レスポンス」を取得できます。 builderを介して HttpClientが作成されます。 ビルダーを使用して、クライアントごとに次のような状態を構成できます。: 優先プロトコル・バージョン(HTTP/1.1またはHTTP/2)、リダイレクトの有無、プロキシ、認証プロバイダなどがあります。一度ビルドされると、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文字列があり、ホストとポートでプロキシ・アドレスを指定します。

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

    • コンストラクタの詳細

      • HttpClient

        protected HttpClient()
        HttpClientを作成します。

    • メソッドの詳細

      • newBuilder

        public static HttpClient.Builder newBuilder()
        新しいHttpClientビルダーを作成します。
        戻り値:
        an HttpClient.Builder

      • cookieHandler

        public abstract Optional<CookieHandler> cookieHandler()
        このクライアントCookieHandlerを含むOptionalを返します。 このクライアントビルダーにCookieHandlerが設定されていない場合、Optionalは空です。
        戻り値:
        このクライアントを含むOptional CookieHandler

      • connectTimeout

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

      • followRedirects

        public abstract HttpClient.Redirect followRedirects()
        このクライアントのフォロー・リダイレクト・ポリシーを返します。 リダイレクト・ポリシーを指定しないBuilderによって構築されたクライアントのデフォルト値は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は空です。
        戻り値:
        このクライアントを含むOptional Authenticator

      • 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には、非同期および依存タスクの実行に使用される「デフォルトのエグゼキュータ」がまだ公開されていないことがあります。

        戻り値:
        このクライアントを含むOptional Executor

      • send

        public abstract <T> HttpResponse<T> send​(HttpRequest request,
                                         HttpResponse.BodyHandler<T> responseBodyHandler)
                                  throws IOException,
                                         InterruptedException
        このクライアントを使用してリクエストを送信し、必要に応じてブロックしてレスポンスを取得します。 返されたHttpResponse <T>には、レスポンス・ステータス、ヘッダー、および本文(指定されたレスポンス本文ハンドラによって処理される)が含まれています。
        型パラメータ:
        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 - レスポンス本文ハンドラ
        戻り値:
        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を拒否した場合、またはプロキシが構成されている場合はプロキシを拒否します。 詳細は、「セキュリティ・チェック」を参照してください。

        型パラメータ:
        T - レスポンス本文型
        パラメータ:
        request - リクエスト
        responseBodyHandler - レスポンス本文ハンドラ
        pushPromiseHandler - プッシュ・プロミス・ハンドラ。nullの可能性があります。
        戻り値:
        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サポートを提供しない場合