Интерфейс WebSocket

public interface WebSocket

Клиент WebSocket.

WebSocket экземпляры создаются через WebSocket.Builder.

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

Метод отправки — любой из методов sendText, sendBinary, sendPing, sendPong и sendClose класса WebSocket. Метод отправки инициирует операцию отправки и возвращает CompletableFuture, которая завершается после завершения операции. Если CompletableFuture завершается нормально, операция считается успешной. Если CompletableFuture завершается с ошибкой, операция считается неудачной. Операция, которая была инициирована, но еще не завершена, считается ожидающей.

Метод приема — любой из методов onText, onBinary, onPing, onPong и onClose класса Listener. WebSocket инициирует операцию приема, вызвав метод приема у слушателя. Затем слушатель должен вернуть CompletionStage, который завершается после завершения операции.

Для управления приёмом сообщений WebSocket использует внутренний счётчик. Значение этого счётчика — количество раз, когда WebSocket ещё должен вызвать метод приема. Пока счётчик равен нулю, WebSocket не вызывает методы приема. Счётчик увеличивается на n при вызове request(n). Счётчик уменьшается на единицу, когда WebSocket вызывает метод приема. onOpen и onError не являются методами приема. WebSocket вызывает onOpen перед любыми другими методами слушателя. WebSocket вызывает onOpen не более одного раза. WebSocket может вызвать onError в любой момент. Если WebSocket вызывает onError или onClose, то дальнейшие вызовы методов слушателя не будут выполнены, независимо от значения счётчика. Для только что созданного WebSocket счётчик равен нулю.

Если не указано иное, аргументы null приведут к тому, что методы WebSocket будут выбрасывать NullPointerException, аналогично, WebSocket не будут передавать аргументы null методам Listener. Состояние WebSocket не изменяется вызовами, которые выбрасывают или возвращают CompletableFuture с завершением одним из исключений NullPointerException, IllegalArgumentException, IllegalStateException.

WebSocket автоматически обрабатывает полученные сообщения Ping и Close (в соответствии с протоколом WebSocket), отвечая сообщениями Pong и Close. Если слушатель получает сообщения Ping или Close, от слушателя не требуется никаких обязательных действий.

Примечание API:
Взаимоотношения между WebSocket и связанным с ним слушателем аналогичны взаимоотношениям между подпиской и связанным с ней подписчиком типа Flow.
С:
11

Вложенные классы

Модификатор и тип Интерфейс Описание
static interface  WebSocket.Builder

Строитель клиентов WebSocket.
static interface  WebSocket.Listener

Интерфейс приема WebSocket.

Поля

Модификатор и тип Поле Описание
static int NORMAL_CLOSURE

Код статуса сообщения WebSocket Close (1000), указывающий на нормальное закрытие, означающее, что цель, для которой было установлено соединение, выполнена.

Методы

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

Прерывает закрытие входной и выходной части WebSocket.
String getSubprotocol()

Возвращает используемый этим WebSocket подпротокол.
boolean isInputClosed()

Определяет, закрыта ли входная часть этого WebSocket.
boolean isOutputClosed()

Определяет, закрыта ли выходная часть этого WebSocket.
void request​(long n)

Увеличивает счётчик вызовов методов приема.
CompletableFuture<WebSocket> sendBinary​(ByteBuffer data, boolean last)

Отправляет двоичные данные из предоставленного буфера.
CompletableFuture<WebSocket> sendClose​(int statusCode, String reason)

Инициирует упорядоченное закрытие выходной части WebSocket, отправив сообщение Close с указанным кодом состояния и причиной.
CompletableFuture<WebSocket> sendPing​(ByteBuffer message)

Отправляет сообщение Ping с байтами из указанного буфера.
CompletableFuture<WebSocket> sendPong​(ByteBuffer message)

Отправляет сообщение Pong с байтами из указанного буфера.
CompletableFuture<WebSocket> sendText​(CharSequence data, boolean last)

Отправляет текстовые данные с символами из заданной последовательности символов.

Поля

NORMAL_CLOSURE

static final int NORMAL_CLOSURE

Код состояния сообщения WebSocket Close (1000), указывающий на нормальное закрытие, означающее, что цель, для которой было установлено соединение, выполнена.

См. также:
sendClose(int, String), WebSocket.Listener.onClose(WebSocket, int, String), Значения константных полей

Методы

sendText

CompletableFuture<WebSocket> sendText(CharSequence data,
                                      boolean last)

Отправляет текстовые данные с символами из заданной последовательности символов.

Последовательность символов не должна изменяться до тех пор, пока CompletableFuture возвращаемое этим методом, не завершится.

Возвращаемое CompletableFuture этим методом может завершиться с исключением:

  • IllegalStateException - если есть ожидающая отправка текста или двоичных данных, или если предыдущие двоичные данные не завершают сообщение
  • IOException - если произошла ошибка ввода-вывода или выходной поток закрыт
Примечание по реализации:
Если data является некорректной последовательностью UTF-16, операция завершится ошибкой IOException.
Параметры:
data - данные
last - true если это вызов завершает сообщение, false в противном случае
Возвращает:
a CompletableFuture, завершающееся с данным WebSocket, когда данные будут отправлены

sendBinary

CompletableFuture<WebSocket> sendBinary(ByteBuffer data,
                                        boolean last)

Отправляет двоичные данные с байтами из заданного буфера.

Данные находятся в байтах от позиции буфера до его предела. После нормального завершения CompletableFuture возвращаемого этим методом, в буфере не останется байтов. К буферу нельзя обращаться до тех пор, пока это не произойдет.

Возвращаемое CompletableFuture этим методом может завершиться с исключением:

  • IllegalStateException - если есть ожидающая отправка текста или двоичных данных, или если предыдущие текстовые данные не завершают сообщение
  • IOException - если произошла ошибка ввода-вывода, или выходной поток закрыт
Параметры:
data - данные
last - true если этот вызов завершает сообщение, false в противном случае
Возвращает:
a CompletableFuture, завершающееся с данным WebSocket, когда данные будут отправлены

sendPing

CompletableFuture<WebSocket> sendPing(ByteBuffer message)

Отправляет сообщение Ping с байтами из заданного буфера.

Сообщение состоит не более чем из 125 байтов от позиции буфера до его предела. После нормального завершения CompletableFuture возвращаемого этим методом, в буфере не останется байтов. К буферу нельзя обращаться до тех пор, пока это не произойдет.

Возвращаемое CompletableFuture этим методом может завершиться с исключением:

  • IllegalStateException - если есть ожидающая отправка ping или pong
  • IllegalArgumentException - если сообщение слишком длинное
  • IOException - если произошла ошибка ввода-вывода или выходной поток закрыт
Параметры:
message - сообщение
Возвращает:
a CompletableFuture, завершающееся с данным WebSocket, когда сообщение Ping будет отправлено

sendPong

CompletableFuture<WebSocket> sendPong(ByteBuffer message)

Отправляет сообщение Pong с байтами из заданного буфера.

Сообщение состоит не более чем из 125 байтов от позиции буфера до его предела. После нормального завершения CompletableFuture возвращаемого этим методом, в буфере не останется байтов. К буферу нельзя обращаться до тех пор, пока это не произойдет.

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

Возвращаемое CompletableFuture этим методом может завершиться с исключением:

  • IllegalStateException - если есть ожидающая отправка ping или pong
  • IllegalArgumentException - если сообщение слишком длинное
  • IOException - если произошла ошибка ввода-вывода, или выходной поток закрыт
Параметры:
message - сообщение
Возвращает:
a CompletableFuture, завершающееся с данным WebSocket, когда сообщение Pong будет отправлено

sendClose

CompletableFuture<WebSocket> sendClose(int statusCode,
                                       String reason)

Инициализирует упорядоченное закрытие вывода данного WebSocket, отправив сообщение Close с заданным кодом состояния и причиной.

statusCode - целое число из диапазона 1000 <= code <= 4999. Коды состояния 1002, 1003, 1006, 1007, 1009, 1010, 1012, 1013 и 1015 некорректны. Поведение по отношению к другим кодам состояния зависит от реализации. Корректная reason - это строка, UTF-8 представление которой не длиннее 123 байтов.

Возвращаемое CompletableFuture этим методом может завершиться с исключением:

  • IllegalArgumentException - если statusCode некорректен, или если reason некорректен
  • IOException - если произошла ошибка ввода-вывода или выходной поток закрыт

Если CompletableFuture возвращаемое этим методом завершается с IllegalArgumentException, или метод бросает исключение NullPointerException, выход будет закрыт.

Если не закрыто уже, вход остаётся открытым до получения сообщения Close получено, или вызова abort, или возникновения ошибки ошибка.

Примечание API:
Используйте предоставленную константу целого числа NORMAL_CLOSURE в качестве кода состояния и пустую строку в качестве причины в типичном случае: 
CompletableFuture<WebSocket> webSocket = ...
    webSocket.thenCompose(ws -> ws.sendText("Hello, ", false))
             .thenCompose(ws -> ws.sendText("world!", true))
             .thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, ""))
             .join();
Метод sendClose не закрывает входной поток этого WebSocket. Он лишь закрывает выходной поток этого WebSocket, отправив сообщение Close. Чтобы закрыть вход, вызовите метод abort. Вот пример приложения, которое отправляет сообщение Close, а затем запускает таймер. После того, как в течение заданного времени не было получено данных, таймер срабатывает, и тревога отменяется WebSocket: 
MyAlarm alarm = new MyAlarm(webSocket::abort);
    WebSocket.Listener listener = new WebSocket.Listener() {

        public CompletionStage<?> onText(WebSocket webSocket,
                                         CharSequence data,
                                         boolean last) {
            alarm.snooze();
            ...
        }
        ...
    };
    ...
    Runnable startTimer = () -> {
        MyTimer idleTimer = new MyTimer();
        idleTimer.add(alarm, 30, TimeUnit.SECONDS);
    };
    webSocket.sendClose(WebSocket.NORMAL_CLOSURE, "ok").thenRun(startTimer);
Параметры:
statusCode - код состояния
reason - причина
Возвращает:
a CompletableFuture, завершающееся с данным WebSocket, когда сообщение Close будет отправлено

request

void request(long n)

Увеличивает счётчик вызовов методов получения.

Этот WebSocket вызовет onText, onBinary, onPing, onPong или onClose методы для связанного слушателя (т.е. методы получения) до n раз.

Примечание API:
Параметр этого метода — количество запрошенных вызовов от этого WebSocket к связанному слушателю, а не количество сообщений. Иногда сообщение может быть доставлено слушателю за один вызов, но не всегда. Например, сообщения Ping, Pong и Close доставляются за один вызов методов onPing, onPong и onClose соответственно. Однако, доставляются ли текстовые и двоичные сообщения за один вызов методов onText и onBinary зависит от булевого аргумента (last) этих методов. Если last равно false, значит в сообщении есть больше данных, чем было доставлено в вызов.

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

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

        StringBuilder text = new StringBuilder();

        public CompletionStage<?> onText(WebSocket webSocket,
                                         CharSequence message,
                                         boolean last) {
            text.append(message);
            if (last) {
                processCompleteTextMessage(text);
                text = new StringBuilder();
            }
            webSocket.request(1);
            return null;
        }
    ...
    }
Параметры:
n - количество вызовов
Исключения:
IllegalArgumentException - если n <= 0

getSubprotocol

String getSubprotocol()

Возвращает подпротокол, используемый этим WebSocket.

Возвращает:
подпротокол или пустую строку, если подпротокола нет

isOutputClosed

boolean isOutputClosed()

Указывает, закрыт ли выходной поток данного WebSocket.

Если этот метод возвращает true, последующие вызовы также вернут true.

Возвращает:
true если закрыто, false в противном случае

isInputClosed

boolean isInputClosed()

Указывает, закрыт ли входной поток данного WebSocket.

Если этот метод возвращает true, последующие вызовы также вернут true.

Возвращает:
true если закрыто, false в противном случае

abort

void abort()

Резко закрывает входной и выходной потоки этого WebSocket.

После возвращения этого метода и входной, и выходной потоки будут закрыты. Любые ожидающие операции отправки завершатся с IOException. Последующие вызовы abort не будут иметь никакого эффекта.

© 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/java.net.http/java/net/http/WebSocket.html

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