Класс HttpExchange

Прямые известные подклассы:
HttpsExchange
public abstract class HttpExchange
extends Object

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

Типичный жизненный цикл HttpExchange показан ниже.

  1. getRequestMethod() для определения команды
  2. getRequestHeaders() для проверки заголовков запроса (при необходимости)
  3. getRequestBody() возвращает InputStream для чтения тела запроса. После чтения тела запроса поток закрывается.
  4. getResponseHeaders() для установки любых заголовков ответа, кроме content-length
  5. sendResponseHeaders(int,long) для отправки заголовков ответа. Должен быть вызван перед следующим шагом.
  6. getResponseBody() для получения OutputStream для отправки тела ответа. Когда тело ответа было записано, поток должен быть закрыт для завершения обмена.
Завершение обменов
Обмены завершаются, когда оба потока ввода запроса и вывода ответа закрываются. Закрытие потока вывода, неявно закрывает поток ввода (если он еще не закрыт). Однако рекомендуется потреблять все данные из потока ввода перед его закрытием. Удобный метод close() выполняет все эти задачи. Закрытие обмена без потребления всего тела запроса не является ошибкой, но может сделать основной TCP-соединение непригодным для последующих обменов. Эффект от невыполнения завершения обмена не определен, но обычно приводит к тому, что ресурсы не освобождаются/не повторно используются.
С:
1.6

Конструкторы

Модификатор Конструктор Описание
protected HttpExchange()

Методы

Модификатор и тип Метод Описание
abstract void close()

Завершает этот обмен, выполняя следующие действия последовательно: закрытие потока ввода запроса, если он еще не закрыт; закрытие потока вывода ответа, если он еще не закрыт.
abstract Object getAttribute​(String name)

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

Возвращает неизменяемую карту, содержащую HTTP-заголовки, которые были включены в этот запрос.
abstract String getRequestMethod()

Получить метод запроса
abstract URI getRequestURI()

Получить URI запроса
abstract OutputStream getResponseBody()

Возвращает поток, в который необходимо записать тело ответа.
abstract int getResponseCode()

Возвращает код ответа, если он уже установлен
abstract Headers getResponseHeaders()

Возвращает изменяемую карту, в которую можно сохранить HTTP-заголовки ответа, которые будут переданы в этом ответе.
abstract void sendResponseHeaders​(int rCode, long responseLength)

Начинает отправку ответа клиенту, используя текущий набор заголовков ответа и числовой код ответа, как указано в этом методе.
abstract void setAttribute​(String name, Object value)

Модули фильтров могут хранить произвольные объекты с экземплярами HttpExchange как механизм внеполосного взаимодействия.
abstract void setStreams​(InputStream i, OutputStream o)

Используется фильтрами для обертывания потоков ввода и вывода этого обмена, с предоставленными отфильтрованными потоками, так что последующие вызовы 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()

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

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

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

getResponseHeaders

public abstract Headers getResponseHeaders()

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

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

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

getRequestURI

public abstract URI getRequestURI()

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

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

getRequestMethod

public abstract String getRequestMethod()

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

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

getHttpContext

public abstract HttpContext getHttpContext()

Получить HttpContext для этого обмена

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

close

public abstract void close()

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

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

getRequestBody

public abstract InputStream getRequestBody()

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

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

getResponseBody

public abstract OutputStream getResponseBody()

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

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

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

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

sendResponseHeaders

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

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

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

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

Параметры:
rCode - код ответа для отправки
responseLength - если > 0, указывает фиксированную длину тела ответа, и необходимо записать в поток, полученный от getResponseBody(), ровно это количество байтов, иначе, если равно 0, используется кодировка chunked, и может быть записано произвольное количество байтов. Если ≤ -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)

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

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

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

setAttribute

public abstract void setAttribute(String name,
                                  Object value)

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

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

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

setStreams

public abstract void setStreams(InputStream i,
                                OutputStream o)

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

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

getPrincipal

public abstract HttpPrincipal getPrincipal()

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

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

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

Spec-Zone .ru
спецификации, руководства, описания, API