Интерфейс 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, 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/java.net.http/java/net/http/WebSocket.Listener.html