Класс HttpExchange

java.lang.Object

com.sun.net.httpserver.HttpExchange

Все реализованные интерфейсы:: Request, AutoCloseable

Прямые известные подклассы:: HttpsExchange

public abstract class HttpExchange extends Object implements AutoCloseable, Request

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

Типичный жизненный цикл одного обмена HttpExchange показан в последовательности ниже:

getRequestMethod() для определения команды.
getRequestHeaders() для проверки заголовков запроса (при необходимости).
getRequestBody() возвращает InputStream для чтения тела запроса. После чтения тела запроса поток должен быть закрыт.
getResponseHeaders() для установки любых заголовков ответа, кроме content-length.
sendResponseHeaders(int,long) для отправки заголовков ответа. Должно быть вызвано перед следующим шагом.
getResponseBody() для получения OutputStream для отправки тела ответа. Когда тело ответа будет записано, поток должен быть закрыт для завершения обмена.

Завершение обменов
Обмены завершаются, когда закрываются и запрос InputStream и ответ OutputStream. Закрытие OutputStream, неявно закрывает InputStream (если он еще не закрыт). Однако рекомендуется потреблять все данные из InputStream перед его закрытием. Метод close() выполняет все эти задачи. Закрытие обмена без потребления всего тела запроса не является ошибкой, но может сделать базовый TCP-соединение непригодным для последующих обменов. Эффект от неудачного завершения обмена не определен, но, как правило, приведет к тому, что ресурсы не будут освобождены/переиспользованы.

С момента:: 1.6

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

HttpExchange()

Модификатор	Конструктор	Описание
`protected`	Конструктор для вызова подклассами.

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

Модификатор и тип	Метод	Описание
`abstract void`	`close()`	Завершает этот обмен, выполнив следующие действия последовательно: закрывает запрос `InputStream`, если он ещё не закрыт.
`abstract Object`	`getAttribute(String name)`	`Filter` модули могут хранить произвольные объекты с помощью `HttpExchange` экземпляров в качестве механизма внеполосной связи.
`abstract HttpContext`	`getHttpContext()`	Возвращает `HttpContext` для этого обмена.
`abstract InetSocketAddress`	`getLocalAddress()`	Возвращает локальный адрес, на котором был получен запрос.
`abstract HttpPrincipal`	`getPrincipal()`	Если для `HttpContext`, владеющего этим обменом, установлен аутентификатор, этот метод вернёт `HttpPrincipal`, представляющий аутентифицированного пользователя для этого `HttpExchange`.
`abstract String`	`getProtocol()`	Возвращает строку протокола из запроса в форме протокол/majorVersion.minorVersion.
`abstract InetSocketAddress`	`getRemoteAddress()`	Возвращает адрес удалённого субъекта, инициировавшего этот запрос.
`abstract InputStream`	`getRequestBody()`	Возвращает поток, из которого можно прочитать тело запроса.
`abstract Headers`	`getRequestHeaders()`	Возвращает неизменяемый `Headers`, содержащий HTTP-заголовки, включённые в этот запрос.
`abstract String`	`getRequestMethod()`	Возвращает метод запроса.

`abstract URI`	`getRequestURI()`	Возвращает запрос `URI`.
`abstract OutputStream`	`getResponseBody()`	Возвращает поток, в который необходимо записать тело ответа.
`abstract int`	`getResponseCode()`	Возвращает код ответа, если он уже установлен.
`abstract Headers`	`getResponseHeaders()`	Возвращает изменяемый `Headers`, в который можно сохранить HTTP-заголовки ответа, которые будут переданы как часть этого ответа.
`abstract void`	`sendResponseHeaders(int rCode, long responseLength)`	Начинает отправку ответа клиенту, используя текущий набор заголовков ответа и числовой код ответа, указанный в этом методе.
`abstract void`	`setAttribute(String name, Object value)`	`Filter` модули могут хранить произвольные объекты с `HttpExchange` экземплярами в качестве механизма внеполосной связи.
`abstract void`	`setStreams(InputStream i, OutputStream o)`	Используется модулями Фильтров для обертывания одного или обоих потоков обмена данного обмена: `InputStream` и `OutputStream` с заданными отфильтрованными потоками, таким образом, последующие вызовы `getRequestBody()` вернут заданный `InputStream`, а вызовы `getResponseBody()` вернут заданный `OutputStream`.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Методы, объявленные в интерфейсе com.sun.net.httpserver.Request

with

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

HttpExchange

protected HttpExchange()

Конструктор для вызова подклассами.

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

getRequestHeaders

public abstract Headers getRequestHeaders()

Возвращает неизменяемый Headers, содержащий HTTP-заголовки, которые были включены в этот запрос.

Ключи в этом Headers — это имена заголовков, а значения — это List строк, содержащих каждое значение, включенное в запрос в порядке его включения. Поля заголовков, появляющиеся несколько раз, представлены как несколько строковых значений.

Ключи в Headers нечувствительны к регистру.

Определено в:: getRequestHeaders в интерфейсе Request
Возвращает:: только для чтения Headers, который можно использовать для доступа к заголовкам запроса.

getResponseHeaders

public abstract Headers getResponseHeaders()

Возвращает изменяемый Headers, в который можно сохранить HTTP-заголовки ответа, которые будут переданы в составе этого ответа.

Ключи в Headers — это имена заголовков, а значения должны быть List строк, содержащих каждое значение, которое должно быть включено несколько раз (в порядке их включения).

Ключи в Headers нечувствительны к регистру.

Возвращает:: изменяемый Headers, который можно использовать для установки заголовков ответа.

getRequestURI

public abstract URI getRequestURI()

Возвращает запрос URI.

Определено в:: getRequestURI в интерфейсе Request
Возвращает:: запрос URI

getRequestMethod

public abstract String getRequestMethod()

Возвращает метод запроса.

Указано в:: getRequestMethod в интерфейсе Request
Возвращает:: строку метода запроса

getHttpContext

public abstract HttpContext getHttpContext()

Возвращает HttpContext для этого обмена.

Возвращает:: HttpContext

close

public abstract void close()

Завершает этот обмен, выполняя следующие действия последовательно:

Закрывает поток ввода запроса InputStream, если он еще не закрыт.
Закрывает поток вывода ответа OutputStream, если он еще не закрыт.

Указано в:: close в интерфейсе AutoCloseable

getRequestBody

public abstract InputStream getRequestBody()

Возвращает поток, из которого можно прочитать тело запроса. Несколько вызовов этого метода вернут один и тот же поток. Рекомендуется, чтобы приложения потребляли (считали) все данные из этого потока перед его закрытием. Если поток закрыт до того, как все данные были прочитаны, вызов InputStream.close() прочитает и удалит оставшиеся данные (до числа байтов, зависящего от реализации).

Возвращает:: поток, из которого можно прочитать тело запроса

getResponseBody

public abstract OutputStream getResponseBody()

Возвращает поток, в который необходимо записать тело ответа. Метод sendResponseHeaders(int,long) должен быть вызван до вызова этого метода. Несколько вызовов этого метода (для одного и того же обмена) вернут один и тот же поток. Для правильного завершения каждого обмена выходной поток должен быть закрыт, даже если тело ответа не отправляется.

Закрытие этого потока неявно закрывает InputStream возвращенный из getRequestBody() (если он еще не закрыт).

Если вызов sendResponseHeaders(int, long) указал фиксированную длину тела ответа, то в этот поток необходимо записать ровно указанное количество байтов. Если будет записано слишком много байтов, то метод write класса OutputStream выбросит IOException. Если будет записано слишком мало байтов, то метод OutputStream.close() потока выбросит IOException. В обоих случаях обмен прерывается, и базовое TCP-соединение закрывается.

Returns:: поток, в который записывается тело ответа

sendResponseHeaders

public abstract void sendResponseHeaders(int rCode, long responseLength) throws IOException

Начинает отправку ответа клиенту с использованием текущего набора заголовков ответа и числового кода ответа, как указано в этом методе. Длина тела ответа также указывается следующим образом. Если параметр длины ответа больше zero, это указывает точное количество байтов для отправки, и приложение должно отправить это точное количество данных. Если параметр длины ответа равен zero, используется кодирование с фрагментами, и может быть отправлено произвольное количество данных. Приложение завершает тело ответа, закрывая OutputStream. Если длина ответа имеет значение -1, тело ответа не отправляется.

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

Этот метод должен быть вызван перед вызовом getResponseBody().

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

Эта реализация позволяет вызывающей стороне указать серверу принудительно закрыть соединение после завершения обмена, предоставив заголовок Connection: close в заголовках ответа заголовков ответа перед вызовом sendResponseHeaders.

Параметры:

rCode - код ответа для отправки

responseLength - если > 0, указывает фиксированную длину тела ответа и точное количество байтов должно быть записано в поток, полученный из getResponseCode() Если == 0, используется кодирование с фрагментами, и может быть записано произвольное количество байтов. Если <= -1, длина тела ответа не задана, и тело ответа не может быть записано.

Исключения:

IOException - если заголовки ответа уже были отправлены или произошла ошибка ввода-вывода

См. также:

getRemoteAddress

public abstract InetSocketAddress getRemoteAddress()

Возвращает адрес удаленного объекта, вызывающего этот запрос.

Возвращает:: адрес InetSocketAddress вызывающей стороны

getResponseCode

public abstract int getResponseCode()

Возвращает код ответа, если он уже задан.

Возвращает:: код ответа, если доступен. -1 если еще недоступен.

getLocalAddress

public abstract InetSocketAddress getLocalAddress()

Возвращает локальный адрес, на котором был получен запрос.

Возвращает:: адрес InetSocketAddress локального интерфейса

getProtocol

public abstract String getProtocol()

Возвращает строку протокола из запроса в формате протокол/majorVersion.minorVersion. Например, "HTTP/1.1".

Возвращает:: строку протокола из запроса

getAttribute

public abstract Object getAttribute(String name)

Модули Filter могут хранить произвольные объекты с HttpExchange экземплярами в качестве механизма внеполосной связи. Другие фильтры или обработчик обмена могут затем получить доступ к этим объектам.

Каждый Filter класс будет документировать атрибуты, которые он предоставляет.

Параметры:: name - имя атрибута для извлечения
Возвращает:: объект атрибута или null , если он не существует
Исключение:: NullPointerException - если имя null

setAttribute

public abstract void setAttribute(String name, Object value)

Каждый Filter класс будет документировать атрибуты, которые он предоставляет.

Параметры:: name - имя, которое нужно связать со значением атрибута; value - объект для хранения в качестве значения атрибута. null значение разрешено.
Исключение:: NullPointerException - если имя null

setStreams

public abstract void setStreams(InputStream i, OutputStream o)

Используется фильтрами Filters для обертывания (или обоих) потоков ввода InputStream и вывода OutputStream текущего обмена фильтрами, чтобы последующие вызовы getRequestBody() возвращали заданные InputStream, а вызовы getResponseBody() — заданные OutputStream. Потоки, предоставленные в этом вызове, должны обертывать исходные потоки и могут (но не обязаны) быть подклассами FilterInputStream и FilterOutputStream.

Parameters:: i - отфильтрованный поток ввода для установки в качестве Inputstream, или null если изменений не требуется; o - отфильтрованный поток вывода для установки в качестве Outputstream, или null если изменений не требуется

getPrincipal

public abstract HttpPrincipal getPrincipal()

Если на HttpContext, владеющем этим обменом, установлен аутентификатор, то этот метод вернёт HttpPrincipal, представляющий аутентифицированного пользователя для этого HttpExchange.

Returns:: аутентифицированного пользователя, или null если аутентификатор не установлен

© 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/jdk.httpserver/com/sun/net/httpserver/HttpExchange.html