Understanding WebSocketHandler

If you are planning to write pure WebSocket application, the WebSocketHandler API is for you. If your application will use other transport like long-polling and http-streaming, or if you want to delegate WebSocket messages to your AtmosphereHandler, take a look at the WebSocketProtocol documentation.

WebSocketHandler

A WebSocketHandler is simple implementation interface that mimic the W3C WebSocket Javascript API. The interface class is defined as:

public interface WebSocketHandler {

    /**
     * Invoked when a byte message is received.
     *
     * @param webSocket a {@link WebSocket}
     * @param data
     * @param offset
     * @param length
     */
    void onByteMessage(WebSocket webSocket, byte[] data, int offset, int length) 
        throws IOException;

    /**
     * Invoked when a String message is received
     *
     * @param webSocket a {@link WebSocket}
     * @param data
     */
    void onTextMessage(WebSocket webSocket, String data) throws IOException;

    /**
     * Invoked when a {@link WebSocket} is opened.
     *
     * @param webSocket
     */
    void onOpen(WebSocket webSocket) throws IOException;

    /**
     * Invoked when a {@link WebSocket} is closed.
     *
     * @param webSocket
     */
    void onClose(WebSocket webSocket);

    /**
     * Invoked when a {@link WebSocket} produces an error.
     *
     * @param webSocket
     */
    void onError(WebSocket webSocket, WebSocketProcessor.WebSocketException t);
}

A simple Chat just consists of:

@WebSocketHandlerService(path = "/chat", broadcaster = SimpleBroadcaster.class)
public class WebSocketChat extends WebSocketHandlerAdapter {

    private final ObjectMapper mapper = new ObjectMapper();

    @Override
    public void onOpen(WebSocket webSocket) throws IOException {
        // Create a communication channel called 'chat' to share messages received.
        webSocket.resource().setBroadcaster(
              BroadcasterFactory.getDefault().lookup("/chat", true));
    }

    public void onTextMessage(WebSocket webSocket, String message) throws IOException {
        AtmosphereResource r = webSocket.resource();
        Broadcaster b = r.getBroadcaster();
        b.broadcast(mapper.writeValueAsString(mapper.readValue(message, Data.class)));
    }
}

You can also stream WebSocket messages (text or binary) instead of letting the underlying WebServer do it for you by implementing the WebSocketStreamingHandler:

public interface WebSocketStreamingHandler extends WebSocketHandler {

    /**
     * Invoked when a byte message is received.
     *
     * @param webSocket a {@link WebSocket}
     * @param inputStream
     */
    void onBinaryStream(WebSocket webSocket, InputStream inputStream) throws IOException;

    /**
     * Invoked when a String message is received
     *
     * @param webSocket a {@link WebSocket}
     * @param reader
     */
    void onTextStream(WebSocket webSocket, Reader reader) throws IOException;

}