Класс 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()`	Возвращает строку протокола из запроса в формате protocol/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)`	Используется фильтрами Filters для обертывания одного или обоих потоков этого обмена — `InputStream` и `OutputStream` — указанными фильтрованными потоками. Благодаря этому последующие вызовы `getRequestBody()` будут возвращать указанный `InputStream`, а вызовы `getResponseBody()` — указанный `OutputStream`.

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

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

Методы, объявленные в интерфейсе Request

with

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

HttpExchange

protected HttpExchange()

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

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

getRequestHeaders

public abstract Headers getRequestHeaders()

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

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

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

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

getResponseHeaders

public abstract Headers getResponseHeaders()

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

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

Ключи в 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) была указана фиксированная длина тела ответа, в этот поток необходимо записать ровно указанное число байтов. При записи слишком большого числа байтов метод записи OutputStream выбросит IOException. Если записано слишком мало байтов, метод OutputStream.close() потока выбросит IOException. В обоих случаях обмен прерывается, а базовое TCP-соединение закрывается.

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

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()

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

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

getAttribute

public abstract Object getAttribute(String name)

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

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

Параметры:: name — имя извлекаемого атрибута
Возвращает:: объект атрибута или null, если атрибут не существует
Выбрасывает:: NullPointerException — если name равно null

setAttribute

public abstract void setAttribute(String name, Object value)

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

Параметры:: name — имя, связываемое со значением атрибута; value — объект, сохраняемый в качестве значения атрибута. Значение null допускается.
Выбрасывает:: NullPointerException — если name равно null

setStreams

public abstract void setStreams(InputStream i, OutputStream o)

Используется фильтрами Filters для обертывания одного или обоих потоков этого обмена — 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://docs.oracle.com/en/java/javase/25/docs/api/jdk.httpserver/com/sun/net/httpserver/HttpExchange.html