Класс 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()

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

закрывает входной поток запроса, если он ещё не закрыт.
закрывает выходной поток ответа, если он ещё не закрыт.

Определено в:: 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-соединение закрывается.

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

sendResponseHeaders

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

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

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

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

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

Эта реализация позволяет вызывающему элементу указать серверу принудительно закрыть соединение после завершения обмена, передав заголовок Connection: close в заголовки ответа before вызов 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()

Возвращает строку протокола из запроса в формате protocol/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 модули могут хранить произвольные объекты с HttpExchange экземплярами в качестве механизма межпроцессного взаимодействия. Другие фильтры или обработчик обмена могут затем получить доступ к этим объектам.

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

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

setStreams

public abstract void setStreams(InputStream i, OutputStream o)

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

Параметры:: i - отфильтрованный входной поток для задания как Inputstream этого объекта, или null, если изменения не нужны; o - отфильтрованный выходной поток для задания как Outputstream этого объекта, или null, если изменения не нужны

getPrincipal

public abstract HttpPrincipal getPrincipal()

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

Возвращает:: HttpPrincipal, или null, если аутентификатор не установлен

© 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://download.java.net/java/early_access/jdk24/docs/api/jdk.httpserver/com/sun/net/httpserver/HttpExchange.html