Sending and Receiving Messages

WebSocket endpoints can send and receive text and binary messages. In addition, they can also send ping frames and receive pong frames. This section describes how to use the Session and RemoteEndpoint interfaces to send messages to the connected peer and how to use the OnMessage annotation to receive messages from it.

The following topics are addressed here:

Sending Messages
Receiving Messages

Sending Messages

Follow these steps to send messages in an endpoint.

Obtain the Session object from the connection.

The Session object is available as a parameter in the annotated lifecycle methods of the endpoint, like those in Table 19-1. When your message is a response to a message from the peer, you have the Session object available inside the method that received the message (the method annotated with @OnMessage). If you have to send messages that are not responses, store the Session object as an instance variable of the endpoint class in the method annotated with @OnOpen so that you can access it from other methods.
Use the Session object to obtain a RemoteEndpoint object.

The Session.getBasicRemote method and the Session.getAsyncRemote method return RemoteEndpoint.Basic and RemoteEndpoint.Async objects respectively. The RemoteEndpoint.Basic interface provides blocking methods to send messages; the RemoteEndpoint.Async interface provides nonblocking methods.
Use the RemoteEndpoint object to send messages to the peer.

The following list shows some of the methods you can use to send messages to the peer. * void RemoteEndpoint.Basic.sendText(String text)

+ Send a text message to the peer. This method blocks until the whole message has been transmitted.
- void RemoteEndpoint.Basic.sendBinary(ByteBuffer data)
  
  Send a binary message to the peer. This method blocks until the whole message has been transmitted.
- void RemoteEndpoint.sendPing(ByteBuffer appData)
  
  Send a ping frame to the peer.
- void RemoteEndpoint.sendPong(ByteBuffer appData)
  
  Send a pong frame to the peer.

The example in Annotated Endpoints demonstrates how to use this procedure to reply to every incoming text message.

Sending Messages to All Peers Connected to an Endpoint

Each instance of an endpoint class is associated with one and only one connection and peer; however, there are cases in which an endpoint instance needs to send messages to all connected peers. Examples include chat applications and online auctions. The Session interface provides the getOpenSessions method for this purpose. The following example demonstrates how to use this method to forward incoming text messages to all connected peers:

@ServerEndpoint("/echoall")
public class EchoAllEndpoint {
   @OnMessage
   public void onMessage(Session session, String msg) {
      try {
         for (Session sess : session.getOpenSessions()) {
            if (sess.isOpen())
               sess.getBasicRemote().sendText(msg);
         }
      } catch (IOException e) { ... }
   }
}

Receiving Messages

The OnMessage annotation designates methods that handle incoming messages. You can have at most three methods annotated with @OnMessage in an endpoint, one for each message type: text, binary, and pong. The following example demonstrates how to designate methods to receive all three types of messages:

@ServerEndpoint("/receive")
public class ReceiveEndpoint {
   @OnMessage
   public void textMessage(Session session, String msg) {
      System.out.println("Text message: " + msg);
   }
   @OnMessage
   public void binaryMessage(Session session, ByteBuffer msg) {
      System.out.println("Binary message: " + msg.toString());
   }
   @OnMessage
   public void pongMessage(Session session, PongMessage msg) {
      System.out.println("Pong message: " +
                          msg.getApplicationData().toString());
   }
}