java.net.http (Java SE 26 & JDK 26)
Description: declaration: module: java.net.http, package: java.net.http
Keywords: java.net.http package

# Package java.net.http

package java.net.http

## HTTP Client and WebSocket APIs

Provides high-level client interfaces to HTTP (versions 1.1, 2, and 3) and low-level client interfaces to WebSocket. The main types defined are:

- `HttpClient`
- `HttpRequest`
- `HttpResponse`
- `WebSocket`

The protocol-specific requirements are defined in the Hypertext Transfer Protocol Version 3 (HTTP/3), the Hypertext Transfer Protocol Version 2 (HTTP/2), the Hypertext Transfer Protocol (HTTP/1.1), and The WebSocket Protocol.

In general, asynchronous tasks execute in either the thread invoking the operation, e.g. sending an HTTP request, or by the threads supplied by the client's `executor`. Dependent tasks, those that are triggered by returned CompletionStages or CompletableFutures, that do not explicitly specify an executor, execute in the same `default executor` as that of `CompletableFuture`, or the invoking thread if the operation completes before the dependent task is registered.

`CompletableFuture`s returned by this API will throw `UnsupportedOperationException` for their `obtrudeValue` and `obtrudeException` methods. Unless otherwise specified, invoking the `cancel` method on a `CompletableFuture` returned by this API may not interrupt the underlying operation, but may be useful to complete, exceptionally, dependent stages that have not already completed.

Unless otherwise stated, `null` parameter values will cause methods of all classes in this package to throw `NullPointerException`.

Since:
  11
External Specifications
  - RFC 9114: HTTP/3
  - RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2)
  - RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
  - RFC 6455: The WebSocket Protocol

- Related Packages
  Module
  Package
  Description
  java.base
  java.net
  Provides the classes for implementing networking applications.
  java.base
  java.net.spi
  Service-provider classes for the `java.net` package.
- Class
  Description
  HttpClient
  An HTTP Client.
  HttpClient.Builder
  A builder of HTTP Clients.
  HttpClient.Redirect
  Defines the automatic redirection policy.
  HttpClient.Version
  The HTTP protocol version.
  HttpConnectTimeoutException
  Thrown when a connection, over which an `HttpRequest` is intended to be sent, is not successfully established within a specified time period.
  HttpHeaders
  A read-only view of a set of HTTP headers.
  HttpOption<T>
  This interface is used to provide additional request configuration option hints on how an HTTP request/response exchange should be carried out by the `HttpClient` implementation.
  HttpOption.Http3DiscoveryMode
  This enumeration can be used to help the `HttpClient` decide how an HTTP/3 exchange should be established, and can be provided as the value of the `HttpOption.H3_DISCOVERY` option to `Builder.setOption`.
  HttpRequest
  An HTTP request.
  HttpRequest.BodyPublisher
  A `BodyPublisher` converts high-level Java objects into a flow of byte buffers suitable for sending as a request body.
  HttpRequest.BodyPublishers
  Implementations of `BodyPublisher` that implement various useful publishers, such as publishing the request body from a String, or from a file.
  HttpRequest.Builder
  A builder of HTTP requests.
  HttpResponse<T>
  An HTTP response.
  HttpResponse.BodyHandler<T>
  A handler for response bodies.
  HttpResponse.BodyHandlers
  Implementations of `BodyHandler` that implement various useful handlers, such as handling the response body as a String, or streaming the response body to a file.
  HttpResponse.BodySubscriber<T>
  A `BodySubscriber` consumes response body bytes and converts them into a higher-level Java type.
  HttpResponse.BodySubscribers
  Implementations of `BodySubscriber` that implement various useful subscribers, such as converting the response body bytes into a String, or streaming the bytes to a file.
  HttpResponse.PushPromiseHandler<T>
  A handler for push promises.
  HttpResponse.PushPromiseHandler.PushId
  Represents a HTTP/3 PushID.
  HttpResponse.PushPromiseHandler.PushId.Http3PushId
  Represents an HTTP/3 PushId.
  HttpResponse.ResponseInfo
  Initial response information supplied to a `BodyHandler` when a response is initially received and before the body is processed.
  HttpTimeoutException
  Thrown when a response is not received within a specified time period.
  StreamLimitException
  An exception raised when the limit imposed for stream creation on an HTTP connection is reached, and the client is unable to create a new stream.
  UnsupportedProtocolVersionException
  Thrown when the HTTP client doesn't support a particular HTTP version.
  WebSocket
  A WebSocket Client.
  WebSocket.Builder
  A builder of WebSocket Clients.
  WebSocket.Listener
  The receiving interface of `WebSocket`.
  WebSocketHandshakeException
  Thrown when the opening handshake has failed.