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

クラスHttpRequest


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

    HttpRequestはHttpRequest builderから作成されます。 HttpRequestビルダーは、HttpRequest.newBuilderを呼び出して取得します。 リクエストURI、ヘッダーと本文を設定できます。 リクエスト・ボディは、DELETE、POST、またはPUTメソッドに提供されるHttpRequest.BodyProcessorオブジェクトを介して提供されます。 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(BodyProcessor.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.BodyProcessorで提供されている以下のリクエスト・プロセッサ実装のいずれかを使用して送信されます。そうでない場合は、カスタム実装を使用できます。

    レスポンス機関

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

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

    複数回答

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

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

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

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

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

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

    セキュリティ・チェック

    セキュリティ・マネージャが存在する場合、セキュリティ・チェックは送信メソッドによって実行されます。 URLPermissionまたはSocketPermissionは、使用されているすべての宛先オリジン・サーバーおよびプロキシ・サーバーにアクセスするために必要です。 URLPermissionはSocketPermissionよりもポリシー・ファイルで優先されるべきです。 権限は、常にシステムのデフォルト・プロキシに暗黙的に付与されます。 プロキシにアクセスするために使用されるURLPermissionフォームは、メソッド・パラメータ"CONNECT" (すべての種類のプロキシ処理)と、"socket://host:port"という形式のURL文字列を使用します。ここで、hostとportはプロキシ・アドレスを指定します。

    例 

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

      HttpRequest request = HttpRequest
              .newBuilder(new URI("http://www.foo.com/"))
              .POST(BodyProcessor.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を作成します。
        戻り値:
        新しいリクエスト・ビルダー

      • bodyProcessor

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

      • method

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

      • duration

        public abstract Duration duration​()
        このリクエストの継続時間を返します。
        戻り値:
        これは期間をリクエスト

      • 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

      • noBody

        public static HttpRequest.BodyProcessor noBody​()
        リクエスト本文を送信しないリクエスト本文ハンドラ。
        戻り値:
        BodyProcessor