- java.lang.Object
-
- 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
-
-
ネストされたクラスのサマリー
ネストされたクラス 修飾子と型 クラス 説明 static interface
HttpClient.Builder
「HTTPクライアント」のビルダー。static class
HttpClient.Redirect
自動リダイレクション・ポリシーを定義します。static class
HttpClient.Version
HTTPプロトコルのバージョン。
-
コンストラクタのサマリー
コンストラクタ 修飾子 コンストラクタ 説明 protected
HttpClient()
HttpClientを作成します。
-
メソッドのサマリー
すべてのメソッド staticメソッド インスタンス・メソッド 抽象メソッド 具象メソッド 修飾子と型 メソッド 説明 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プロトコル・バージョンを返します。
-
-
-
メソッドの詳細
-
newHttpClient
public static HttpClient newHttpClient()
デフォルト設定を使用して新しいHttpClient
を返します。newBuilder().build()
と等価です。デフォルト設定には: "GET"リクエスト・メソッド、HTTP/2のプリファレンス、NEVERのリダイレクション・ポリシー、「デフォルト・プロキシ・セレクタ」、および「デフォルトのSSLコンテキスト」があります。
- 実装上のノート:
- システム全体のデフォルト値は、
HttpClient
インスタンスの構築時に取得されます。 たとえばProxySelector.setDefault(ProxySelector)
またはSSLContext.setDefault(SSLContext)
を呼び出して、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サポートを提供しない場合
-
-