Интерфейс 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)`	Устанавливает указанную пару «имя — значение» в наборе заголовков этого запроса.
`default <T> HttpRequest.Builder`	`setOption(HttpOption<T> option, T value)`	Предоставляет подсказки о параметрах конфигурации запроса в виде пар «ключ — значение», чтобы реализация `HttpClient` могла определить, как следует установить или выполнить обмен запросом и ответом.
`HttpRequest.Builder`	`timeout(Duration duration)`	Устанавливает время ожидания для этого запроса.
`HttpRequest.Builder`	`uri(URI uri)`	Устанавливает `HttpRequest` запроса `URI` этого построителя.
`HttpRequest.Builder`	`version(HttpClient.Version version)`	Устанавливает предпочтительную `HttpClient.Version` для этого запроса.

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

uri

HttpRequest.Builder uri(URI uri)

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

Параметры:: 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
Возвращает:: этот построитель

setOption

default <T> HttpRequest.Builder setOption(HttpOption<T> option, T value)

Предоставляет подсказки о параметрах конфигурации запроса в виде пар «ключ — значение», чтобы реализация HttpClient могла определить, как следует установить или выполнить обмен запросом и ответом.

Реализация HttpClient может проигнорировать подсказки о параметрах конфигурации запроса или завершить запрос с ошибкой, если получит подсказки для параметров, которые ей неизвестны.

Если этот метод вызывается дважды для одного и того же параметра запроса, новое значение заменяет ранее переданное этому построителю значение соответствующего параметра. Если в качестве значения указано null, ранее переданное значение отбрасывается.

Требования к реализации:

Реализация этого метода по умолчанию отбрасывает переданную подсказку о параметре и ничего не делает.

Примечание по реализации:

Встроенная реализация JDK для HttpClient распознаёт подсказку о параметре запроса HttpOption.H3_DISCOVERY.

Параметры:

option — параметр конфигурации запроса

value — значение параметра конфигурации запроса (может быть null)

Возвращает:

этот построитель

Начиная с версии:

См. также:

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, то есть ожиданию без конца.

Требования к реализации:

Время ожидания применяется к промежутку времени, который начинается в момент запуска выполнения запроса и длится как минимум до момента создания HttpResponse. В это время входит установление соединения для передачи данных и получение заголовков ответа.

Примечание по реализации:

Встроенная реализация JDK применяет время ожидания ко всему промежутку от момента запуска выполнения запроса до момента получения тела ответа, если оно есть. Для этого таймер останавливается после завершения подписчика тела ответа.

Параметры:

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.