Package 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	Description
default void	onBinary(java.nio.ByteBuffer buffer, boolean isLast, DoneCallback onComplete)	Called when a message is received from the client.
default void	onBinary(java.nio.ByteBuffer buffer, boolean isLast, DoneCallback doneAndPullData, java.lang.Runnable releaseBuffer)	Called when a message is received from the client.
void	onClientClosed(int statusCode, java.lang.String reason)	Called when the client has closed the connection.
void	onConnect(MuWebSocketSession session)	Called when the websocket is connected.
void	onError(java.lang.Throwable cause)	Called when an unexpected error occurs.
void	onPing(java.nio.ByteBuffer payload, DoneCallback onComplete)	Called when a ping message is sent from a client.
void	onPong(java.nio.ByteBuffer payload, DoneCallback onComplete)	Called when a pong message is sent from the client.
default void	onText(java.lang.String message, boolean isLast, DoneCallback onComplete)	Called when a message is received from the client.

Method Detail

onConnect

void onConnect(MuWebSocketSession session)
        throws java.lang.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:

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

onText

default void onText(java.lang.String message,
                    boolean isLast,
                    DoneCallback onComplete)
             throws java.lang.Exception

Called when a message is received from the client.

Parameters:

message - The message as a string.

isLast - Returns true if this message is the last part of the complete message. This is only false when clients send fragmented messages in which case only the last part of the fragmented message will return true.

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

Throws:

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

onBinary

default void onBinary(java.nio.ByteBuffer buffer,
                      boolean isLast,
                      DoneCallback onComplete)
               throws java.lang.Exception

Called when a message is received from the client.

Parameters:

buffer - The message as a byte buffer.

isLast - Returns true if this message is the last part of the complete message. This is only false when clients send fragmented messages in which case only the last part of the fragmented message will return true.

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:

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

onBinary

default void onBinary(java.nio.ByteBuffer buffer,
                      boolean isLast,
                      DoneCallback doneAndPullData,
                      java.lang.Runnable releaseBuffer)
               throws java.lang.Exception

Called when a message is received from the client. Consider using this API when separation of control for pulling data and releasing buffer are required. Otherwise, please use onBinary(ByteBuffer, boolean, DoneCallback) instead.

Parameters:

buffer - The message as a byte buffer.

isLast - Returns true if this message is the last part of the complete message. This is only false when clients send fragmented messages in which case only the last part of the fragmented message will return true.

doneAndPullData - A callback that must be run with doneAndPullData.onComplete() when ready to pull more data from websocket.

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

Throws:

java.lang.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,
                    java.lang.String reason)
             throws java.lang.Exception

Called when the client has closed the connection.

The connection should be closed on the server side when this is received. If overriding BaseWebSocket this occurs automatically.

Parameters:

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

reason - An optional reason for the closure.

Throws:

java.lang.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(java.nio.ByteBuffer payload,
            DoneCallback onComplete)
     throws java.lang.Exception

Called when a ping message is sent from a client.

When received, a websocket should send the data back in a pong message. If overriding BaseWebSocket this occurs automatically.

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:

java.lang.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(java.nio.ByteBuffer payload,
            DoneCallback onComplete)
     throws java.lang.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:

java.lang.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(java.lang.Throwable cause)
      throws java.lang.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, boolean, DoneCallback) etc (but not onError itself).
• The client sends an invalid frame

Parameters:

cause - The cause of the error

Throws:

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