Интерфейс HttpRequest.Builder

Вмещающий класс:: HttpRequest

public static interface HttpRequest.Builder

Построитель HTTP-запросов.

Экземпляры HttpRequest.Builder создаются вызовом HttpRequest.newBuilder(), HttpRequest.newBuilder(URI) или HttpRequest.newBuilder(HttpRequest, BiPredicate).

Построитель можно использовать для настройки состояния отдельного запроса, например URI запроса, метода запроса (по умолчанию используется GET, если явно не задан другой метод), определённых заголовков запроса и т. д. Каждый метод установки изменяет состояние построителя и возвращает тот же экземпляр. Методы не синхронизированы, поэтому их не следует вызывать из нескольких потоков без внешней синхронизации. Метод build возвращает новый HttpRequest при каждом вызове. Созданный HttpRequest является неизменяемым и может отправляться несколько раз.

Обратите внимание: пользовательский код не может устанавливать все заголовки запросов. Некоторые заголовки ограничены по соображениям безопасности, а управление другими, например заголовками, связанными с аутентификацией, перенаправлением и файлами cookie, может осуществляться специальными API, а не путём непосредственной установки заголовков пользователем.

Начиная с:: 11

Краткое описание методов

Модификатор и тип	Метод	Описание
`HttpRequest`	`build()`	Создаёт и возвращает `HttpRequest`.
`HttpRequest.Builder`	`copy()`	Возвращает точную копию этого `Builder` на основе текущего состояния.
`HttpRequest.Builder`	`DELETE()`	Устанавливает для этого построителя метод запроса DELETE.
`HttpRequest.Builder`	`expectContinue(boolean enable)`	Запрашивает у сервера подтверждение запроса перед отправкой тела.
`HttpRequest.Builder`	`GET()`	Устанавливает для этого построителя метод запроса GET.
`default HttpRequest.Builder`	`HEAD()`	Устанавливает для этого построителя метод запроса HEAD.
`HttpRequest.Builder`	`header(String name, String value)`	Добавляет указанную пару «имя — значение» в набор заголовков этого запроса.
`HttpRequest.Builder`	`headers(String... headers)`	Добавляет указанные пары «имя — значение» в набор заголовков этого запроса.
`HttpRequest.Builder`	`method(String method, HttpRequest.BodyPublisher bodyPublisher)`	Устанавливает для этого построителя метод и тело запроса, используя указанные значения.
`HttpRequest.Builder`	`POST(HttpRequest.BodyPublisher bodyPublisher)`	Устанавливает для этого построителя метод запроса POST и задаёт указанную издательскую сущность тела запроса.
`HttpRequest.Builder`	`PUT(HttpRequest.BodyPublisher bodyPublisher)`	Устанавливает для этого построителя метод запроса PUT и задаёт указанную издательскую сущность тела запроса.
`HttpRequest.Builder`	`setHeader(String name, String value)`	Устанавливает указанную пару «имя — значение» в набор заголовков этого запроса.
`HttpRequest.Builder`	`timeout(Duration duration)`	Устанавливает время ожидания для этого запроса.
`HttpRequest.Builder`	`uri(URI uri)`	Устанавливает `URI` запроса этого `HttpRequest`.
`HttpRequest.Builder`	`version(HttpClient.Version version)`	Устанавливает предпочтительную `HttpClient.Version` для этого запроса.

Подробное описание методов

uri

HttpRequest.Builder uri(URI uri)

Устанавливает URI запроса этого HttpRequest.

Параметры:: uri — URI запроса
Возвращает:: этот построитель
Вызывает исключение:: IllegalArgumentException — если схема URI не поддерживается

expectContinue

HttpRequest.Builder expectContinue(boolean enable)

Запрашивает у сервера подтверждение запроса перед отправкой тела. По умолчанию эта возможность отключена. Если она включена, серверу предлагается отправить ответ с ошибкой или ответ 100 Continue, прежде чем клиент отправит тело запроса. Это означает, что издатель запроса не будет вызван до получения этого промежуточного ответа.

Параметры:: enable — true, если следует отправить Expect continue
Возвращает:: этот построитель

version

HttpRequest.Builder version(HttpClient.Version version)

Устанавливает предпочтительную HttpClient.Version для этого запроса.

Следует проверить HttpResponse, чтобы узнать, какая версия фактически использовалась. Если версия не задана в запросе, будет запрошена версия, используемая отправляющим запрос HttpClient.

Параметры:: version — запрашиваемая версия протокола HTTP
Возвращает:: этот построитель

header

HttpRequest.Builder header(String name, String value)

Добавляет указанную пару «имя — значение» в набор заголовков этого запроса. Указанное значение добавляется в список значений для этого имени.

Примечание по реализации:: Реализация может ограничивать некоторые имена или значения заголовков, поскольку HTTP-клиент может самостоятельно определять их значения. Например, значение "Content-Length" определяется издателем запроса. В таком случае реализация HttpRequest.Builder может выбросить IllegalArgumentException, если такой заголовок передан построителю.
Параметры:: name — имя заголовка; value — значение заголовка
Возвращает:: этот построитель
Вызывает исключение:: IllegalArgumentException — если имя или значение заголовка недопустимо (см. раздел 3.2 RFC 7230) либо реализация ограничивает имя или значение заголовка.

headers

HttpRequest.Builder headers(String... headers)

Добавляет указанные пары «имя — значение» в набор заголовков этого запроса. Переданные экземпляры String должны чередоваться: сначала имена заголовков, затем их значения. Чтобы добавить несколько значений для одного имени, необходимо указывать это имя перед каждым новым значением.

Параметры:: headers — список пар «имя — значение»
Возвращает:: этот построитель
Вызывает исключение:: IllegalArgumentException — если указано нечётное число параметров, имя или значение заголовка недопустимо (см. раздел 3.2 RFC 7230) либо реализация ограничивает имя или значение заголовка.

timeout

HttpRequest.Builder timeout(Duration duration)

Устанавливает время ожидания для этого запроса. Если ответ не получен в течение указанного времени, из HttpClient::send выбрасывается HttpTimeoutException, либо выполнение HttpClient::sendAsync завершается с исключением HttpTimeoutException. Если время ожидания не задано, это равносильно установке бесконечного значения Duration, то есть ожиданию без ограничения времени.

Параметры:: duration — продолжительность ожидания
Возвращает:: этот построитель
Вызывает исключение:: IllegalArgumentException — если продолжительность неположительна

setHeader

HttpRequest.Builder setHeader(String name, String value)

Устанавливает указанную пару «имя — значение» в набор заголовков этого запроса. При этом перезаписываются все ранее заданные значения для этого имени.

Параметры:: name — имя заголовка; value — значение заголовка
Возвращает:: этот построитель
Вызывает исключение:: IllegalArgumentException — если имя или значение заголовка недопустимо (см. раздел 3.2 RFC 7230) либо реализация ограничивает имя или значение заголовка.

GET

HttpRequest.Builder GET()

Устанавливает для этого построителя метод запроса GET. Это значение используется по умолчанию.

Возвращает:: этот построитель

POST

HttpRequest.Builder POST(HttpRequest.BodyPublisher bodyPublisher)

Устанавливает для этого построителя метод запроса POST и задаёт указанную издательскую сущность тела запроса.

Параметры:: bodyPublisher — издательская сущность тела
Возвращает:: этот построитель

PUT

HttpRequest.Builder PUT(HttpRequest.BodyPublisher bodyPublisher)

Устанавливает для этого построителя метод запроса PUT и задаёт указанную издательскую сущность тела запроса.

Параметры:: bodyPublisher — издательская сущность тела
Возвращает:: этот построитель

DELETE

HttpRequest.Builder DELETE()

Устанавливает для этого построителя метод запроса DELETE.

Возвращает:: этот построитель

HEAD

default HttpRequest.Builder HEAD()

Устанавливает для этого построителя метод запроса HEAD.

Требования к реализации:: Ожидается, что реализация по умолчанию будет вести себя так же, как: return method("HEAD", BodyPublishers.noBody());
Возвращает:: этот построитель
Начиная с:: 18

method

HttpRequest.Builder method(String method, HttpRequest.BodyPublisher bodyPublisher)

Устанавливает для этого построителя метод и тело запроса, используя указанные значения.

Примечание API:: Издательскую сущность тела запроса noBody можно использовать, если тело запроса не требуется или неуместно. Ограничения на использование методов зависят от реализации. Например, некоторые реализации могут ограничивать метод CONNECT.
Параметры:: method — используемый метод; bodyPublisher — издательская сущность тела
Возвращает:: этот построитель
Вызывает исключение:: IllegalArgumentException — если имя метода недопустимо (см. раздел 3.1.1 RFC 7230) либо реализация ограничивает этот метод.

build

HttpRequest build()

Создаёт и возвращает HttpRequest.

Требования к реализации:: Этот метод возвращает новый HttpRequest при каждом вызове. Созданный HttpRequest является неизменяемым и может отправляться несколько раз.
Возвращает:: новый HttpRequest
Вызывает исключение:: IllegalStateException — если URI не задан

copy

HttpRequest.Builder copy()

Возвращает точную копию этого Builder на основе текущего состояния. Новый построитель можно изменять независимо от этого построителя.

Возвращает:: точную копию этого построителя

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/HttpRequest.Builder.html