モジュール jdk.incubator.httpclient
パッケージ jdk.incubator.http

クラスHttpRequest

  • public abstract class HttpRequest
extends Object
    サーバーに送信できる1つのHTTPリクエストを表します。
    インキュベーション機能。将来のリリースで削除されます。

    HttpRequestインスタンスは、HttpRequest buildersから構築されます。 HttpRequestビルダーは、HttpRequest.newBuilderを呼び出して取得します。 リクエストURI、ヘッダーと本文を設定できます。 リクエスト・ボディは、DELETE、POST、またはPUTメソッドに提供されるHttpRequest.BodyPublisherオブジェクトを介して提供されます。 GETは身体をとりません。 ビルダーに必要なすべてのパラメータが設定されると、HttpRequest.Builder.build()が呼び出されてHttpRequestが返されます。 いくつかのパラメータが異なる複数の関連するリクエストを構築するために、ビルダーを複数回コピーして変更することもできます。

    2つの単純なHTTPインタラクションの例を以下に示します: 

     
      HttpClient client = HttpClient.newHttpClient();

      // GET
      HttpResponse<String> response = client.send(
          HttpRequest
              .newBuilder(new URI("http://www.foo.com/"))
              .headers("Foo", "foovalue", "Bar", "barvalue")
              .GET()
              .build(),
          BodyHandler.asString()
      );
      int statusCode = response.statusCode();
      String body = response.body();

      // POST
      HttpResponse<Path> response = client.send(
          HttpRequest
              .newBuilder(new URI("http://www.foo.com/"))
              .headers("Foo", "foovalue", "Bar", "barvalue")
              .POST(BodyPublisher.fromString("Hello world"))
              .build(),
          BodyHandler.asFile(Paths.get("/path"))
      );
      int statusCode = response.statusCode();
      Path body = response.body(); // should be "/path"

    HttpClientで次のいずれかのメソッドを呼び出すと、リクエストが送信され、レスポンスが取得されます。

    HttpResponseが受信されると、ヘッダー、レスポンス・コード、本文(typically)が利用可能になります。 本文が読み込まれたかどうかは、レスポンス本体の型<T>によって決まります。 後述の説明を参照してください。

    同期と非同期の使用方法については、以下を参照してください。

    リクエスト団体

    リクエスト・ボディは、HttpRequest.BodyPublisherで提供される以下のコンビニエンス・リクエスト・パブリッシャ実装の1つを使用して送信できます。 また、カスタムのPublisher実装を使用することもできます。

    レスポンス機関

    レスポンス機関は2つのレベルで扱われます。 リクエストを送信するときは、レスポンス本文ハンドラが指定されます。 これは、レスポンス・ステータス・コードとヘッダーが受信されると呼び出される関数(HttpResponse.BodyHandler)です。 この関数は、HttpResponse.BodySubscriber <T>を返すと予想され、レスポンス本文を読み取ってTのインスタンスに変換します。 これが発生すると、レスポンスはHttpResponseで利用可能になり、HttpResponse.body()を呼び出して実際の本文を取得することができます。 HttpResponse.BodySubscriberとHttpResponse.BodyHandlerの両方の使用法と実装例は、HttpResponseで提供されています:

    「あらかじめ定義された本文ハンドラの一部」

    複数回答

    HTTP/2では、サーバーがメインのレスポンスとゼロ以上の追加のレスポンス(サーバー・プッシュと呼ばれる)をクライアントが開始したリクエストに返すことが可能です。 これらは、HttpResponse.MultiSubscriberという特別なレスポンス・サブスクライバを使用して処理されます。

    ブロッキング/非同期動作とスレッドの使用

    リクエスト送信には2つのスタイルがあります: synchronousとasynchronousです。 HttpClient.send(HttpRequest, HttpResponse.BodyHandler)は、リクエストが送信され、レスポンスが受信されるまで、呼び出しスレッドをブロックします。

    HttpClient.sendAsync(HttpRequest, HttpResponse.BodyHandler)は非同期で、すぐにCompletableFuture<HttpResponse>を返し、このオブジェクトがを完了(おそらく別のスレッドに)するとレスポンスを受信しました。

    HttpClient.sendAsync(HttpRequest, HttpResponse.MultiSubscriber)はマルチ・レスポンスの変形であり、非同期です。

    CompletableFutureのインスタンスは、いくつかの非同期タスク間の依存関係を宣言するためにさまざまな方法で組み合わせることができ、最大レベルの並列処理を利用することができます。

    セキュリティ・チェック

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

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

    例 

    
      HttpClient client = HttpClient
              .newBuilder()
              .build();

      HttpRequest request = HttpRequest
              .newBuilder(new URI("http://www.foo.com/"))
              .POST(BodyPublisher.fromString("Hello world"))
              .build();

      HttpResponse<Path> response =
          client.send(request, BodyHandler.asFile(Paths.get("/path")));

      Path body = response.body();

    非同期の例

    sendの代わりに(HttpRequest, HttpResponse.BodyHandler) sendAsyncが使用されている場合、上記の例は非同期で動作します。この場合、返されるオブジェクトはHttpResponseの代わりにCompletableFuture <HttpResponse>です。 次の例は、複数のリクエストを非同期で送信する方法を示しています。 また、CompletableFutureの多くのメソッドの1つを使用して、依存関係のない非同期操作(レスポンスを受信し、レスポンス本文を受信)を簡単にチェーンする方法を示します。 

     
  // fetch a list of target URIs asynchronously and store them in Files.

      List<URI> targets = ...

      List<CompletableFuture<File>> futures = targets
          .stream()
          .map(target -> client
                  .sendAsync(
                      HttpRequest.newBuilder(target)
                                 .GET()
                                 .build(),
                      BodyHandler.asFile(Paths.get("base", target.getPath())))
                  .thenApply(response -> response.body())
                  .thenApply(path -> path.toFile()))
          .collect(Collectors.toList());

      // all async operations waited for here

      CompletableFuture.allOf(futures.toArray(new CompletableFuture<?>[0]))
          .join();

      // all elements of futures have completed and can be examined.
      // Use File.exists() to check whether file was successfully downloaded

    特に明記されていない限り、nullのパラメータ値により、このクラスのメソッドはNullPointerExceptionをスローします。

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

    • コンストラクタの詳細

      • HttpRequest

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

    • メソッドの詳細

      • newBuilder

        public static HttpRequest.Builder newBuilder​(URI uri)
        HttpRequest Builderを作成します。
        パラメータ:
        uri - リクエストURI
        戻り値:
        新しいリクエスト・ビルダー
        例外:
        IllegalArgumentException - URIスキームがサポートされていない場合。

      • newBuilder

        public static HttpRequest.Builder newBuilder()
        HttpRequest Builderを作成します。
        戻り値:
        新しいリクエスト・ビルダー

      • bodyPublisher

        public abstract Optional<HttpRequest.BodyPublisher> bodyPublisher()
        このリクエストで設定されたHttpRequest.BodyPublisherを含むOptionalを返します。 BodyPublisherがリクエスト・ビルダーに設定されていない場合、Optionalは空です。
        戻り値:
        このリクエストを含むOptional BodyPublisher

      • method

        public abstract String method()
        このリクエストのリクエスト・メソッドを返します。 明示的に設定されていない場合、任意のリクエストに対するデフォルトのメソッドは"GET"です。
        戻り値:
        このリクエスト・メソッド

      • timeout

        public abstract Optional<Duration> timeout()
        このリクエスト・タイムアウト期間を含むOptionalを返します。 リクエスト・ビルダーでタイムアウト時間が設定されていない場合、Optionalは空です。
        戻り値:
        このリクエスト・タイムアウト時間を含むOptional

      • expectContinue

        public abstract boolean expectContinue()
        expect continue の設定を返します。
        戻り値:
        このリクエストは設定を続けることを期待しています

      • uri

        public abstract URI uri()
        このリクエスト・リクエストURIを返します。
        戻り値:
        このリクエストURI

      • version

        public abstract Optional<HttpClient.Version> version()
        このHttpRequestにリクエストされるHTTPプロトコル・バージョンを含むOptionalを返します。 リクエスト・ビルダーにバージョンが設定されていない場合、Optionalは空です。 その場合、リクエストされたバージョンは送信するHttpClientのバージョンになります。 実際に使用されたバージョンを確認するには、対応するHttpResponseを問合せする必要があります。
        戻り値:
        HTTPプロトコル・バージョン

      • headers

        public abstract HttpHeaders headers()
        (user-accessible)リクエスト・ヘッダーは、このリクエストが送信された(または)でした。
        戻り値:
        このリクエストHttpHeaders

      • equals

        public final boolean equals​(Object obj)
        このHTTPリクエスト・インスタンスが指定されたオブジェクトと等しいかどうかをテストします。

        指定されたオブジェクトがHttpRequestでない場合、このメソッドはfalseを返します。 URI、メソッド、およびヘッダー・フィールドがすべて等しい場合、2つのHTTPリクエストは等しいです。

        このメソッドはObject.equalsメソッドの汎用規約を満たします。

        オーバーライド:
        equals 、クラス:  Object
        パラメータ:
        obj - このオブジェクトが比較されるオブジェクト
        戻り値:
        指定されたオブジェクトがこのHTTPリクエストと等しい HttpRequestである場合にのみtrue
        関連項目:
        Object.hashCode()、HashMap

      • hashCode

        public final int hashCode()
        このHTTPリクエスト・インスタンスのハッシュ・コードを計算します。

        ハッシュ・コードは、HTTPリクエストのURI、メソッド、およびヘッダー・コンポーネントに基づいており、Object.hashCodeメソッドの汎用規約を満たしています。

        オーバーライド:
        hashCode 、クラス:  Object
        戻り値:
        このHTTPリクエストのハッシュ・コード値
        関連項目:
        Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)