io.muserver

Interface MuWebSocket

All Known Implementing Classes:

BaseWebSocket

public interface MuWebSocket

An interface defining the callbacks received on a websocket which is returned by MuWebSocketFactory.create(MuRequest, Headers).

In order to listen to events, implement this interface and store the reference to the MuWebSocketSession when onConnect(MuWebSocketSession) is called.

Important: The callbacks are called within on an NIO event thread, therefore there should be no blocking calls in the callbacks (any blocking IO should be passed to another thread). The methods that receive a ByteBuffer in this interface provide a DoneCallback parameter which should be called when the buffer is no longer needed. If this is not called, then no more messages will be received.

Note: Rather than implementing this, you may wish to extend the BaseWebSocket class which handles ping events and captures the socket session, exposing it via the BaseWebSocket.session() method.

Method Summary

Modifier and Type	Method and Description
void	onBinary(ByteBuffer buffer, DoneCallback onComplete) Called when a message is received from the client.
void	onClientClosed(int statusCode, String reason) Called when the client has closed the connection.
void	onConnect(MuWebSocketSession session) Called when the websocket is connected.
void	onError(Throwable cause) Called when an unexpected error occurs.
void	onPing(ByteBuffer payload, DoneCallback onComplete) Called when a ping message is sent from a client.
void	onPong(ByteBuffer payload, DoneCallback onComplete) Called when a pong message is sent from the client.
void	onText(String message, DoneCallback onComplete) Called when a message is received from the client.

Method Detail

onConnect

void onConnect(MuWebSocketSession session)
        throws Exception

Called when the websocket is connected.

Parameters:

session - The websocket session, which can be used to send messages, pings, and close the connection.

Throws:

Exception - Any exceptions thrown will result in the onError method being called with the thrown exception being used as the cause parameter.

onText

void onText(String message,
            DoneCallback onComplete)
     throws Exception

Called when a message is received from the client.

Parameters:

message - The message as a string.

onComplete - A callback that must be run with onComplete.run() when the byte buffer is no longer needed.

Throws:

Exception - Any exceptions thrown will result in the onError method being called with the thrown exception being used as the cause parameter.

onBinary

void onBinary(ByteBuffer buffer,
              DoneCallback onComplete)
       throws Exception

Called when a message is received from the client.

Parameters:

buffer - The message as a byte buffer.

onComplete - A callback that must be run with onComplete.run() when the byte buffer is no longer needed. Failure to call this will result in memory leaks.

Throws:

Exception - Any exceptions thrown will result in the onError method being called with the thrown exception being used as the cause parameter.

onClientClosed

void onClientClosed(int statusCode,
                    String reason)
             throws Exception

Called when the client has closed the connection.

Parameters:

statusCode - The closure code. See https://tools.ietf.org/html/rfc6455#section-7.4

reason - An optional reason for the closure.

Throws:

Exception - Any exceptions thrown will result in the onError method being called with the thrown exception being used as the cause parameter.

onPing

void onPing(ByteBuffer payload,
            DoneCallback onComplete)
     throws Exception

Called when a ping message is sent from a client.

Parameters:

payload - The ping payload.

onComplete - A callback that must be run with onComplete.run() when the byte buffer is no longer needed. Failure to call this will result in memory leaks.

Throws:

Exception - Any exceptions thrown will result in the onError method being called with the thrown exception being used as the cause parameter.

onPong

void onPong(ByteBuffer payload,
            DoneCallback onComplete)
     throws Exception

Called when a pong message is sent from the client.

Parameters:

payload - The pong payload

onComplete - A callback that must be run with onComplete.run() when the byte buffer is no longer needed. Failure to call this will result in memory leaks.

Throws:

Exception - Any exceptions thrown will result in the onError method being called with the thrown exception being used as the cause parameter.

onError

void onError(Throwable cause)
      throws Exception

Called when an unexpected error occurs. Possible errors include, but are not limited to:

• The client shuts down non-gracefully in which case the cause will be a ClientDisconnectedException (note that if the client initiates a graceful shutdown, then onClientClosed(int, String) will be called instead)
• No messages have been received within the time specified by WebSocketHandlerBuilder.withIdleReadTimeout(long, TimeUnit), in which case the cause will be a TimeoutException
• An Exception is thrown by any of the methods that implement this interface, such as onText(String, DoneCallback) etc (but not onError itself).
• The client sends an invalid frame, in which case cause will be WebSocketProtocolException

Parameters:

cause - The cause of the error

Throws:

Exception - Any exceptions thrown will result in the connection being closed.