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

Внешний интерфейс:: WebSocket

public static interface WebSocket.Listener

Интерфейс-получатель для WebSocket.

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

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

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

Примечание 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, 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://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/WebSocket.Listener.html