JSR 356, Java API для WebSocket

Следующий фрагмент кода напечатает причину закрытия WebSocket:

@OnClose
public void myOnClose (CloseReason reason) {
   System.out.prinlnt ("Closing a WebSocket due to "+reason.getReasonPhrase());
}

Чтобы завершить, есть еще одна аннотация жизненного цикла: в случае получения ошибки @OnErrorбудет вызван метод, помеченный как.

Управляемый интерфейсом подход

Подход, основанный на аннотациях, позволяет нам аннотировать класс и методы Java аннотациями жизненного цикла. Используя подход интерфейса с приводом, разработчик расширяет javax.websocket.Endpointи отменяет onOpen, onCloseи onErrorметоды:

public class myOwnEndpoint extends javax.websocket.Endpoint {
   public void onOpen(Session session, EndpointConfig config) {...}
   public void onClose(Session session, CloseReason closeReason) {...}
   public void onError (Session session, Throwable throwable) {...}
}

Для перехвата сообщений в реализации javax.websocket.MessageHandlerнеобходимо зарегистрировать onOpen:

public void onOpen (Session session, EndpointConfig config) {
   session.addMessageHandler (new MessageHandler() {...});
}

MessageHandlerинтерфейс с двумя подинтерфейсами: MessageHandler.Partialи MessageHandler.Whole. MessageHandler.PartialИнтерфейс должен быть использован , когда разработчик хочет получать уведомления о частичных поставках сообщений, а также реализация MessageHandler.Wholeдолжна быть использована для уведомления о прибытии полного сообщения.

Следующий фрагмент кода прослушивает входящие текстовые сообщения и отправляет версию текстового сообщения в верхнем регистре другому узлу:

public void onOpen (Session session, EndpointConfig config) {
   final RemoteEndpoint.Basic remote = session.getBasicRemote();
   session.addMessageHandler (new MessageHandler.Whole<String>() {
      public void onMessage(String text) {
                 try {
                     remote.sendString(text.toUpperCase());
                 } catch (IOException ioe) {
                     // handle send failure here
                 }
             }

   });
}

Типы сообщений, кодеры и декодеры

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

В основном, есть три разных типа сообщений:

• Текстовые сообщения
• Двоичные сообщения
• Сообщения Pong, касающиеся самого соединения с WebSocket

При использовании модели, управляемой интерфейсом, каждый сеанс может регистрировать не более одного MessageHandlerдля каждого из этих трех различных типов сообщений.

При использовании модели на основе аннотаций для каждого отдельного типа сообщения @onMessageдопускается один аннотированный метод. Допустимые параметры для указания содержимого сообщения в аннотированных методах зависят от типа сообщения.

В Javadoc для @OnMessageаннотации четко указаны допустимые параметры сообщения в зависимости от типа сообщения (из Javadoc указано следующее):

• «если метод обрабатывает текстовые сообщения:
  • String получить целое сообщение
  • Примитив Java или эквивалент класса для получения всего сообщения, преобразованного в этот тип
  • String и логическая пара для получения сообщения по частям
  • Reader получить сообщение целиком в виде блокирующего потока
  • любой параметр объекта, для которого конечная точка имеет текстовый декодер ( Decoder.Textили Decoder.TextStream).
• если метод обрабатывает двоичные сообщения:
  • byte[]или ByteBufferполучить сообщение целиком
  • byte[]и логическая пара, или ByteBufferлогическая пара, чтобы получить сообщение по частям
  • InputStream получить сообщение целиком в виде блокирующего потока
  • любой параметр объекта, для которого конечная точка имеет двоичный декодер ( Decoder.Binaryили Decoder.BinaryStream).
• если метод обрабатывает сообщения pong:
  • PongMessage для обработки сообщений понг

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

Кодер определен как реализация javax.websocket.Encoderинтерфейса, а декодер — реализация javax.websocket.Decoderинтерфейса. Каким-то образом экземплярам конечной точки необходимо знать, каковы возможные кодеры и декодеры. Использование подхода аннотаций привода, список кодеров и декодеров пропускают через кодер и декодер элементов в @ClientEndpointи @ServerEndpointаннотации.

Код в листинге 1 показывает, как зарегистрировать MessageEncoderкласс, который определяет преобразование экземпляра MyJavaObjectв текстовое сообщение. MessageDecoderКласс зарегистрирован для преобразования противоположного.

@ServerEndpoint(value="/endpoint", encoders = MessageEncoder.class, decoders= MessageDecoder.class)
public class MyEndpoint {
...
}

class MessageEncoder implements Encoder.Text<MyJavaObject> {
   @override
   public String encode(MyJavaObject obj) throws EncodingException {
      ...
   }
}

class MessageDecoder implements Decoder.Text<MyJavaObject> {
   @override 
   public MyJavaObject decode (String src) throws DecodeException {
      ...
   }

   @override 
   public boolean willDecode (String src) {
      // return true if we want to decode this String into a MyJavaObject instance
   }
}

Листинг 1

EncoderИнтерфейс имеет ряд субинтерфейсов: