Java Magazine, Jan/Feb 2016

ORACLE COM JAVAMAGAZINE JANUARY FEBRUARY 2016 50 web apps public void sendText String partialTextMessage boolean isLast throws IOException or public void sentBinary ByteBuffer partialBinaryMessage boolean isLast throws IOException depending on the type of message you wish to send Asynchronous sending of messages Receipt of WebSocket messages is always asynchronous An endpoint typically has no idea when messages are going to arrive they just appear whenever the peer chooses Now all the methods of the RemoteEndpoint Basic interface for sending messages most of which we have seen are synchronous sends In simple terms what this means is that the send method calls always block until the message has been transmitted This is fine for small messages but if the message is large a WebSocket may well have better things to do than wait for it to send such as messaging someone else repainting a user interface or focusing more resources on processing incoming messages For such endpoints the RemoteEndpoint Async obtainable from the Session object as is the RemoteEndpoint Basic contains send methods that take a whole message as a parameter in various forms It returns immediately and before the message passed in is actually sent For example when sending a large text message you might want to use the public void sendText String textMessage SendHandler handler method The method returns immediately and the Send Handler that you pass in to this method receives a callback when the message is actually transmitted In this way you know the message was sent but you dont have to wait around until it does so Or you may want to check in periodically on the progress of an asynchronous message send For example you might choose the method public Future Void sendText String textMessage in which case the method returns immediately and before the message is transmitted You can query the Future object you obtain in return for the status of the message sent and even cancel transmission if you change your mind There are binary message equivalents for these methods as you might expect Before we leave the topic of sending messages in the Java WebSocket API its worth pointing out that the WebSocket protocol has no built in notion of delivery guarantee In other words when you send a message you dont know for sure whether it was received by the client If you receive an error in your error handler methods thats usually a sure sign that the message was not delivered properly But if there is no error the message still may not have been properly delivered It is possible to build interactions yourself in Java WebSockets wherein for important messages you have the peer send you an acknowledgement of receipt But unlike other messaging protocols such as JMS there is no inherent guarantee of delivery Path Mapping In the Clock example there was one endpoint and it was mapped to a single relative URI in the URI space of the web application The client that connected to this endpoint did so by choosing a URL that was exactly that of the URI to the web application plus the URI of the endpoint This is an example of exact path mapping in the Java WebSocket API