Класс HttpExchange

java.lang.Object

com.sun.net.httpserver.HttpExchange

Все реализуемые интерфейсы:: AutoCloseable

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

public abstract class HttpExchange extends Object implements AutoCloseable

Этот класс инкапсулирует полученный 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()`	Возвращает неизменяемую `Map`, содержащую HTTP-заголовки, которые были включены в этот запрос.
`abstract String`	`getRequestMethod()`	Получить метод запроса.
`abstract URI`	`getRequestURI()`	Получить запрос `URI`.
`abstract OutputStream`	`getResponseBody()`	Возвращает поток, в который необходимо записать тело ответа.
`abstract int`	`getResponseCode()`	Возвращает код ответа, если он уже установлен.
`abstract Headers`	`getResponseHeaders()`	Возвращает изменяемую `Map`, в которую можно сохранить 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

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

HttpExchange

protected HttpExchange()

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

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

getRequestHeaders

public abstract Headers getRequestHeaders()

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

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

Возвращает:: только для чтения Map для доступа к заголовкам запроса

getResponseHeaders

public abstract Headers getResponseHeaders()

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

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

Возвращает:: записываемое Map для установки заголовков ответа.

getRequestURI

public abstract URI getRequestURI()

Получить URI запроса.

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

getRequestMethod

public abstract String getRequestMethod()

Получить метод запроса.

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

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

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

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

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

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

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

Параметры:

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

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

Исключения:

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

См. также:

getResponseBody()

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 - отфильтрованный поток ввода, который необходимо установить в качестве потока ввода этого объекта, или null если изменений не требуется; o - отфильтрованный поток вывода, который необходимо установить в качестве потока вывода этого объекта, или null если изменений не требуется

getPrincipal

public abstract HttpPrincipal getPrincipal()

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

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

© 1993, 2021, 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/17/docs/api/jdk.httpserver/com/sun/net/httpserver/HttpExchange.html