18.5 Sending and Receiving Messages

18.5.1 Sending Messages

Follow these steps to send messages in an endpoint.

1. 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 18-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.

2. 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.

3. 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.

@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) { ... }
   }
}

18.5.2 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());
   }
}