| // ======================================================================== |
| // Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd. |
| // ======================================================================== |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| |
| [[jetty-websocket-api-send-message]] |
| === Send Messages to Remote Endpoint |
| |
| The most important feature of the Session is access to the link:{JDURL}/org/eclipse/jetty/websocket/api/RemoteEndpoint.html[`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]] |
| ==== Blocking Send Message |
| |
| Most calls are blocking in nature, and will not return until the send has completed (or has thrown an exception). |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [[partial]] |
| ==== 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`). |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [[pingpong]] |
| ==== Send Ping / Pong Control Frame |
| |
| You can also send Ping and Pong control frames using the RemoteEndpoint. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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]] |
| ==== Async Send Message |
| |
| However there are also 2 Async send message methods available: |
| |
| * link:{JDURL}/org/eclipse/jetty/websocket/api/RemoteEndpoint.html#sendBytesByFuture(java.nio.ByteBuffer)[`RemoteEndpoint.sendBytesByFuture(ByteBuffer message)`] |
| * link:{JDURL}/org/eclipse/jetty/websocket/api/RemoteEndpoint.html#sendStringByFuture(java.lang.String)[`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 http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html[`java.util.concurrent.Future`] behavior. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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. |