Version: 9.4.2.v20170220 |

Send Messages to Remote Endpoint
Previous | Chapter 27. Jetty Websocket API Home | Next

##### Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development

## Send Messages to Remote Endpoint

The most important feature of the Session is access to the `org.eclipse.jetty.websocket.api.RemoteEndpoint`needed to send messages.

With RemoteEndpoint you can choose to send TEXT or BINARY WebSocket messages, or the WebSocket PING and PONG control frames.

### Blocking Send Message

Most calls are blocking in nature, and will not return until the send has completed (or has thrown an exception).

    RemoteEndpoint remote = session.getRemote();

    // Blocking Send of a BINARY message to remote endpoint
    ByteBuffer buf = ByteBuffer.wrap(new byte[] { 0x11, 0x22, 0x33, 0x44 });
    try
    {
        remote.sendBytes(buf);
    }
    catch (IOException e)
    {
        e.printStackTrace(System.err);
    }

How to send a simple Binary message using the RemoteEndpoint. This will block until the message is sent, possibly throwing an IOException if unable to send the message.

    RemoteEndpoint remote = session.getRemote();

    // Blocking Send of a TEXT message to remote endpoint
    try
    {
        remote.sendString("Hello World");
    }
    catch (IOException e)
    {
        e.printStackTrace(System.err);
    }

How to send a simple Text message using the RemoteEndpoint. This will block until the message is sent, possibly throwing an IOException if unable to send the message.

### Send Partial Message

If you have a large message to send, and want to send it in pieces and parts, you can utilize the partial message sending methods of RemoteEndpoint. Just be sure you finish sending your message (`isLast == true`).

    RemoteEndpoint remote = session.getRemote();

    // Blocking Send of a BINARY message to remote endpoint
    // Part 1
    ByteBuffer buf1 = ByteBuffer.wrap(new byte[] { 0x11, 0x22 });
    // Part 2 (last part)
    ByteBuffer buf2 = ByteBuffer.wrap(new byte[] { 0x33, 0x44 });
    try
    {
        remote.sendPartialBytes(buf1,false);
        remote.sendPartialBytes(buf2,true); // isLast is true
    }
    catch (IOException e)
    {
        e.printStackTrace(System.err);
    }

How to send a Binary message in 2 parts, using the partial message support in RemoteEndpoint. This will block until each part of the message is sent, possibly throwing an IOException if unable to send the partial message.

    RemoteEndpoint remote = session.getRemote();

    // Blocking Send of a TEXT message to remote endpoint
    String part1 = "Hello";
    String part2 = " World";
    try
    {
        remote.sendPartialString(part1,false);
        remote.sendPartialString(part2,true); // last part
    }
    catch (IOException e)
    {
        e.printStackTrace(System.err);
    }

How to send a Text message in 2 parts, using the partial message support in RemoteEndpoint. This will block until each part of the message is sent, possibly throwing an IOException if unable to send the partial message.

### Send Ping / Pong Control Frame

You can also send Ping and Pong control frames using the RemoteEndpoint.

    RemoteEndpoint remote = session.getRemote();

    // Blocking Send of a PING to remote endpoint
    String data = "You There?";
    ByteBuffer payload = ByteBuffer.wrap(data.getBytes());
    try
    {
        remote.sendPing(payload);
    }
    catch (IOException e)
    {
        e.printStackTrace(System.err);
    }

How to send a Ping control frame, with a payload of `"You There?"` (arriving at Remote Endpoint as a byte array payload). This will block until the message is sent, possibly throwing an IOException if unable to send the ping frame.

    RemoteEndpoint remote = session.getRemote();

    // Blocking Send of a PONG to remote endpoint
    String data = "Yup, I'm here";
    ByteBuffer payload = ByteBuffer.wrap(data.getBytes());
    try
    {
        remote.sendPong(payload);
    }
    catch (IOException e)
    {
        e.printStackTrace(System.err);
    }

How to send a Pong control frame, with a payload of `"Yup I'm here"` (arriving at Remote Endpoint as a byte array payload). This will block until the message is sent, possibly throwing an IOException if unable to send the pong frame.

To be correct in your usage of Pong frames, you should return the same byte array data that you received in the Ping frame.

### Async Send Message

However there are also 2 Async send message methods available:

- `RemoteEndpoint.sendBytesByFuture(ByteBuffer message)`
- `RemoteEndpoint.sendStringByFuture(String message)`

Both return a `Future<Void>` that can be used to test for success and failure of the message send using standard `java.util.concurrent.Future` behavior.

    RemoteEndpoint remote = session.getRemote();

    // Async Send of a BINARY message to remote endpoint
    ByteBuffer buf = ByteBuffer.wrap(new byte[] { 0x11, 0x22, 0x33, 0x44 });
    remote.sendBytesByFuture(buf);

How to send a simple Binary message using the RemoteEndpoint. The message will be enqueued for outgoing write, but you will not know if it succeeded or failed.

    RemoteEndpoint remote = session.getRemote();

    // Async Send of a BINARY message to remote endpoint
    ByteBuffer buf = ByteBuffer.wrap(new byte[] { 0x11, 0x22, 0x33, 0x44 });
    try
    {
        Future<Void> fut = remote.sendBytesByFuture(buf);
        // wait for completion (forever)
        fut.get();
    }
    catch (ExecutionException | InterruptedException e)
    {
        // Send failed
        e.printStackTrace();
    }

How to send a simple Binary message using the RemoteEndpoint, tracking the `Future<Void>` to know if the send succeeded or failed.

    RemoteEndpoint remote = session.getRemote();

    // Async Send of a BINARY message to remote endpoint
    ByteBuffer buf = ByteBuffer.wrap(new byte[] { 0x11, 0x22, 0x33, 0x44 });
    Future<Void> fut = null;
    try
    {
        fut = remote.sendBytesByFuture(buf);
        // wait for completion (timeout)
        fut.get(2,TimeUnit.SECONDS);
    }
    catch (ExecutionException | InterruptedException e)
    {
        // Send failed
        e.printStackTrace();
    }
    catch (TimeoutException e)
    {
        // timeout
        e.printStackTrace();
        if (fut != null)
        {
            // cancel the message
            fut.cancel(true);
        }
    }

How to send a simple Binary message using the RemoteEndpoint, tracking the `Future<Void>` and waiting only prescribed amount of time for the send to complete, cancelling the message if the timeout occurs.

    RemoteEndpoint remote = session.getRemote();

    // Async Send of a TEXT message to remote endpoint
    remote.sendStringByFuture("Hello World");

How to send a simple Text message using the RemoteEndpoint. The message will be enqueued for outgoing write, but you will not know if it succeeded or failed.

    RemoteEndpoint remote = session.getRemote();

    // Async Send of a TEXT message to remote endpoint
    try
    {
        Future<Void> fut = remote.sendStringByFuture("Hello World");
        // wait for completion (forever)
        fut.get();
    }
    catch (ExecutionException | InterruptedException e)
    {
        // Send failed
        e.printStackTrace();
    }

How to send a simple Binary message using the RemoteEndpoint, tracking the `Future<Void>` to know if the send succeeded or failed.

    RemoteEndpoint remote = session.getRemote();

    // Async Send of a TEXT message to remote endpoint
    Future<Void> fut = null;
    try
    {
        fut = remote.sendStringByFuture("Hello World");
        // wait for completion (timeout)
        fut.get(2,TimeUnit.SECONDS);
    }
    catch (ExecutionException | InterruptedException e)
    {
        // Send failed
        e.printStackTrace();
    }
    catch (TimeoutException e)
    {
        // timeout
        e.printStackTrace();
        if (fut != null)
        {
            // cancel the message
            fut.cancel(true);
        }
    }

How to send a simple Binary message using the RemoteEndpoint, tracking the `Future<Void>` and waiting only prescribed amount of time for the send to complete, cancelling the message if the timeout occurs.

Previous | Top | Next
WebSocket Session | Home | Using WebSocket Annotations

See an error or something missing? Contribute to this documentation at Github!(Generated: 2017-02-20)