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

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final long`	`RSPBODY_CHUNKED`	Длина тела ответа не указана; оно будет передаваться с кодированием по частям
`static final long`	`RSPBODY_EMPTY`	В этом ответе тело не отправляется

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

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

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

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли этот объект другому объекту.
`protected void`	`finalize()`	Устарел и подлежит удалению: этот элемент API может быть удален в будущей версии. Финализация устарела и может быть удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения указанного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения указанного промежутка реального времени.

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

with

Модификатор и тип	Метод	Описание
`default Request`	`with(String headerName, List<String> headerValues)`	Возвращает идентичный `Request` с дополнительным заголовком.

Подробное описание полей

RSPBODY_EMPTY

public static final long RSPBODY_EMPTY

В этом ответе тело не отправляется

Начиная с:

См. также:

RSPBODY_CHUNKED

public static final long RSPBODY_CHUNKED

Длина тела ответа не указана; оно будет передаваться с кодированием по частям

Начиная с:

См. также:

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

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, он задает точное количество отправляемых байтов, и приложение должно отправить именно это количество данных. Если параметр длины ответа равен RSPBODY_CHUNKED (ноль), тело ответа передается с кодированием по частям и можно отправить произвольное количество данных. Приложение завершает передачу тела ответа, закрывая OutputStream. Если длина ответа равна RSPBODY_EMPTY, тело ответа не отправляется.

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

Этот метод необходимо вызвать до вызова getResponseBody().

Примечание API:

Если тело ответа отправляется из массива байтов и длина массива используется в качестве параметра responseLength, обратите внимание на поведение в случае пустого массива. В этом случае responseLength будет равен нулю — значению RSPBODY_CHUNKED, в результате чего тело ответа нулевой длины будет передано с кодированием по частям. Хотя это допустимо, может быть предпочтительнее проверить, пуст ли массив, и вместо этого задать responseLength равным RSPBODY_EMPTY. Кроме того, при отправке тела ответа с кодированием по частям независимо от его длины обработчик должен явно закрыть поток вывода.

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

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

Параметры:

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

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

Выбрасывает:

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)

Используется фильтрами для обертывания одного или обоих потоков этого обмена — 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.