type=page
status=published
title=Sending and Receiving Messages
next=websocket006.html
prev=websocket004.html
~~~~~~
Sending and Receiving Messages
==============================

[[BABFCGBJ]]

[[sending-and-receiving-messages]]
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:

* link:#CIHEHFCB[Sending Messages]
* link:#CIHIDFHD[Receiving Messages]

[[CIHEHFCB]]

[[sending-messages]]
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
link:websocket004.html#BABDGEJH[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.
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 link:websocket004.html#BABFEBGA[Annotated Endpoints]
demonstrates how to use this procedure to reply to every incoming text
message.

[[BABIFBCG]]

[[sending-messages-to-all-peers-connected-to-an-endpoint]]
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:

[source,oac_no_warn]
----
@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) { ... }
   }
}
----

[[CIHIDFHD]]

[[receiving-messages]]
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:

[source,oac_no_warn]
----
@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());
   }
}
----
