Интерфейс 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.

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

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

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

webSocket.request(1);
return null;

Параметры:

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

message - сообщение

Возвращает:

onPong

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

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

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

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

webSocket.request(1);
return null;

Параметры:

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

message - сообщение

Возвращает:

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, 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.
https://download.java.net/java/early_access/jdk24/docs/api/java.net.http/java/net/http/WebSocket.Listener.html