モジュール java.net.http

パッケージ java.net.http

クラスHttpClient

java.lang.Object

java.net.http.HttpClient

public abstract class HttpClient extends Object

HTTPクライアント。

HttpClientを使用して「リクエスト」を送信し、「レスポンス」を取得できます。 builderを介して HttpClientが作成されます。 newBuilderメソッドは、デフォルトの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

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

ネストされたクラス

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

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

コンストラクタ

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

メソッドのサマリー

修飾子と型	メソッド	説明
abstract Optional<Authenticator>	authenticator()	このクライアントに設定されたAuthenticatorを含むOptionalを返します。
abstract Optional<Duration>	connectTimeout()	このクライアントの「接続タイムアウト時間」を含むOptionalを返します。
abstract Optional<CookieHandler>	cookieHandler()	このクライアントCookieHandlerを含むOptionalを返します。
abstract Optional<Executor>	executor()	このクライアントExecutorを含むOptionalを返します。
abstract HttpClient.Redirect	followRedirects()	このクライアントのフォロー・リダイレクト・ポリシーを返します。
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)	指定されたレスポンス本文ハンドラとともにこのクライアントを使用して、指定されたリクエストを非同期に送信し、プッシュ・プロミス・ハンドラをプッシュします。
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は空です。

戻り値:

このクライアントを含む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>には、レスポンス・ステータス、ヘッダー、および本文(指定されたレスポンス本文ハンドラによって処理される)が含まれています。

演算が中断された場合、デフォルトの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 - レスポンス本文ハンドラ

戻り値:

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の可能性があります。

戻り値:

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サポートを提供しない場合