Интерфейс 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)`	Устанавливает запрос `HttpRequest` этого `HttpRequest`.
`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
Возвращает:: этот билдер

header

HttpRequest.Builder header(String name, String value)

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

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

headers

HttpRequest.Builder headers(String... headers)

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

Параметры:: headers - список пар имя-значение
Возвращает:: этот билдер
Исключения:: IllegalArgumentException - если количество параметров нечётное, или имя или значение заголовка не валидны, см. RFC 7230 раздел-3.2, или имя или значение заголовка ограничены реализацией.

timeout

HttpRequest.Builder timeout(Duration duration)

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

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

setHeader

HttpRequest.Builder setHeader(String name, String value)

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

Параметры:: name - имя заголовка; value - значение заголовка
Возвращает:: этот билдер
Исключения:: IllegalArgumentException - если имя или значение заголовка не валидны, см. RFC 7230 раздел-3.2, или имя или значение заголовка ограничены реализацией.

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 - если имя метода не валидно, см. RFC 7230 раздел-3.1.1, или метод ограничен реализацией.

build

HttpRequest build()

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

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

copy

HttpRequest.Builder copy()

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

Возвращает:: точная копия этого билдера

© 1993, 2023, 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/21/docs/api/java.net.http/java/net/http/HttpRequest.Builder.html