Интерфейс WebSocket.Listener

Окружающий интерфейс:: WebSocket

public static interface WebSocket.Listener

Интерфейс для приема данных от WebSocket.

Объект WebSocket вызывает методы связанного слушателя, передавая себя в качестве аргумента. Эти методы вызываются в потокобезопасном режиме, так что следующее обращение может начаться только после завершения предыдущего.

При получении данных, WebSocket вызывает метод для получения. Методы onText, onBinary, onPing и onPong должны возвращать CompletionStage, который завершается, как только сообщение будет получено слушателем. Если метод слушателя возвращает null вместо CompletionStage, WebSocket будет вести себя так, как если бы слушатель вернул CompletionStage, который уже завершен успешно.

Исключение IOException , возникающее в WebSocket, приведет к вызову onError с этим исключением (если вход не закрыт). Если метод слушателя выбрасывает исключение или CompletionStage возвращённое из метода завершается с ошибкой, WebSocket вызовет onError с этим исключением.

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

Строгий последовательный порядок вызовов от WebSocket к Listener означает, в частности, что методы Listener обрабатываются как нерекурсивные. Это означает, что реализациям Listener не нужно беспокоиться о возможной рекурсии или порядке, в котором они вызывают WebSocket.request относительно своей логики обработки.

Внимание может потребоваться, если слушатель связан более чем с одним WebSocket. В этом случае вызовы, связанные с различными экземплярами WebSocket могут не быть упорядочены и могут даже происходить одновременно.

CompletionStage возвращаемые из методов получения не имеют отношения к счетчику вызовов. То есть, CompletionStage не обязан завершиться, чтобы получить дополнительные вызовы методов слушателя. Вот пример слушателя, который запрашивает вызовы по одному, пока не будет накоплено полное сообщение, затем обрабатывает результат и завершает CompletionStage:

    WebSocket.Listener listener = new WebSocket.Listener() {

    List<CharSequence> parts = new ArrayList<>();
    CompletableFuture<?> accumulatedMessage = new CompletableFuture<>();

    public CompletionStage<?> onText(WebSocket webSocket,
                                     CharSequence message,
                                     boolean last) {
        parts.add(message);
        webSocket.request(1);
        if (last) {
            processWholeText(parts);
            parts = new ArrayList<>();
            accumulatedMessage.complete(null);
            CompletionStage<?> cf = accumulatedMessage;
            accumulatedMessage = new CompletableFuture<>();
            return cf;
        }
        return accumulatedMessage;
    }
};

С тех пор:

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

Модификатор и тип	Метод	Описание
`default CompletionStage<?>`	`onBinary(WebSocket webSocket, ByteBuffer data, boolean last)`	Получено двоичное данные.
`default CompletionStage<?>`	`onClose(WebSocket webSocket, int statusCode, String reason)`	Получено сообщение Close, указывающее на закрытие ввода WebSocket.
`default void`	`onError(WebSocket webSocket, Throwable error)`	Произошла ошибка.
`default void`	`onOpen(WebSocket webSocket)`	Соединение `WebSocket` установлено.
`default CompletionStage<?>`	`onPing(WebSocket webSocket, ByteBuffer message)`	Получено сообщение Ping.
`default CompletionStage<?>`	`onPong(WebSocket webSocket, ByteBuffer message)`	Получено сообщение Pong.
`default CompletionStage<?>`	`onText(WebSocket webSocket, CharSequence data, boolean last)`	Получено текстовые данные.

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

onOpen

default void onOpen(WebSocket webSocket)

Соединение с WebSocket установлено.

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

Требования к реализации:

Стандартная реализация эквивалентна:

webSocket.request(1);

Параметры:

webSocket - подключенный WebSocket

onText

default CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last)

Получено текстовое данные.

Верните CompletionStage, который будет использоваться WebSocket в качестве сигнала о возможности освобождения CharSequence. Не обращайтесь к CharSequence после завершения данного CompletionStage.

Требования к реализации:

Стандартная реализация эквивалентна:

webSocket.request(1);
return null;

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

data всегда является допустимой последовательностью UTF-16.

Параметры:

webSocket - WebSocket, на котором получены данные

data - данные

last - указывает, завершает ли этот вызов сообщение

Возвращаемое значение:

CompletionStage, завершающийся, когда CharSequence можно освободить; или null, если его можно освободить немедленно

onBinary

default CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer data, boolean last)

Получены двоичные данные.

Эти данные расположены в байтах от позиции буфера до его предела.

Верните CompletionStage, который будет использоваться WebSocket в качестве сигнала о возможности освобождения ByteBuffer. Не обращайтесь к ByteBuffer после завершения этого CompletionStage.

Требования к реализации:

Стандартная реализация эквивалентна:

webSocket.request(1);
return null;

Параметры:

webSocket - WebSocket, на котором получены данные

data - данные

last - указывает, завершает ли этот вызов сообщение

Возвращаемое значение:

CompletionStage, завершающийся, когда ByteBuffer можно освободить; или null, если его можно освободить немедленно

onPing

default CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer message)

Получено сообщение Ping.

Согласно протоколу WebSocket, сообщение содержит не более 125 байт. Эти байты расположены от позиции буфера до его предела.

Поскольку реализация WebSocket автоматически отправляет ответ pong при получении ping, редко требуется явно отправлять сообщение pong при получении ping.

Требования к реализации:

Стандартная реализация эквивалентна:

webSocket.request(1);
return null;

Параметры:

webSocket - WebSocket, на котором получено сообщение

message - сообщение

Возвращаемое значение:

CompletionStage, завершающийся, когда ByteBuffer можно освободить; или null, если его можно освободить немедленно

onPong

default CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer message)

Получено сообщение Pong.

Требования к реализации:

Стандартная реализация эквивалентна:

webSocket.request(1);
return null;

Параметры:

webSocket - WebSocket, на котором получено сообщение

message - сообщение

Возвращаемое значение:

CompletionStage, завершающийся, когда ByteBuffer можно освободить; или null, если его можно освободить немедленно

onClose

default CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason)

Получает сообщение Close, указывающее на закрытие ввода WebSocket.

Это последний вызов от указанного WebSocket. К моменту начала этого вызова вход WebSocket будет закрыт.

Сообщение Close состоит из кода состояния и причины закрытия. Код состояния — целое число из диапазона 1000 <= code <= 65535. reason — строка с представлением UTF-8, длина которой не превышает 123 байт.

Если вывод WebSocket еще не закрыт, CompletionStage , возвращаемое этим методом, будет использовано в качестве сигнала о возможности закрытия вывода WebSocket. WebSocket закроет свой вывод в ближайшее время, в зависимости от завершения возвращенного CompletionStage или вызова методов sendClose или abort.

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

Возврат CompletionStage , который никогда не завершается, фактически отключает взаимное закрытие вывода.

Для указания пользовательского кода закрытия или кода причины закрытия метод sendClose можно вызвать внутри вызова onClose:

   public CompletionStage<?> onClose(WebSocket webSocket,
                        int statusCode,
                        String reason) {
    webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
    return new CompletableFuture<Void>();
}

Требования к реализации:

Стандартная реализация этого метода возвращает null, указывая на то, что вывод должен быть закрыт немедленно.

Параметры:

webSocket - WebSocket, на котором получено сообщение

statusCode - код состояния

reason - причина

Возвращаемое значение:

CompletionStage, завершающийся, когда WebSocket можно закрыть; или null, если его можно закрыть немедленно

onError

default void onError(WebSocket webSocket, Throwable error)

Произошла ошибка.

Это последний вызов от указанного WebSocket. К моменту начала этого вызова как вход, так и вывод WebSocket будут закрыты. WebSocket может вызвать этот метод у связанного слушателя в любое время после вызова onOpen, независимо от того, были ли запрошены какие-либо вызовы от WebSocket.

Если из этого метода произойдет исключение, поведение не определено.

Параметры:: webSocket - WebSocket, на котором произошла ошибка; error - ошибка

© 1993, 2023, 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/21/docs/api/java.net.http/java/net/http/WebSocket.Listener.html