Package io.muserver

Class BaseWebSocket

java.lang.Object

io.muserver.BaseWebSocket

All Implemented Interfaces:

MuWebSocket

public abstract class BaseWebSocket
extends java.lang.Object
implements MuWebSocket

A base class for server-side web sockets, that takes care of capturing the web socket session, responding to pings, and closure events.

This is an alternative to implementing the MuWebSocket interface and is recommended so that any additions to the interface are non-breaking to implementors.

Constructor Summary

Constructors

Constructor	Description
BaseWebSocket()

Method Summary

Modifier and Type	Method	Description
void	onBinary(java.nio.ByteBuffer buffer, boolean isLast, DoneCallback onComplete)	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.
void	onText(java.lang.String message, boolean isLast, DoneCallback onComplete)	Called when a message is received from the client.
protected MuWebSocketSession	session()	Gets the websocket session
protected WebsocketSessionState	state()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.muserver.MuWebSocket

onBinary

Constructor Detail

BaseWebSocket

public BaseWebSocket()

Method Detail

state

protected WebsocketSessionState state()

Returns:

The state of the current session

onConnect

public void onConnect(MuWebSocketSession session)
               throws java.lang.Exception

Description copied from interface: MuWebSocket

Called when the websocket is connected.

Specified by:

onConnect in interface MuWebSocket

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

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

Description copied from interface: MuWebSocket

Called when a message is received from the client.

Specified by:

onText in interface MuWebSocket

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

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

Description copied from interface: MuWebSocket

Called when a message is received from the client.

Specified by:

onBinary in interface MuWebSocket

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.

onClientClosed

public void onClientClosed(int statusCode,
                           java.lang.String reason)
                    throws java.lang.Exception

Description copied from interface: MuWebSocket

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.

Specified by:

onClientClosed in interface MuWebSocket

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

public void onPing(java.nio.ByteBuffer payload,
                   DoneCallback onComplete)
            throws java.lang.Exception

Description copied from interface: MuWebSocket

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.

Specified by:

onPing in interface MuWebSocket

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

public void onPong(java.nio.ByteBuffer payload,
                   DoneCallback onComplete)
            throws java.lang.Exception

Description copied from interface: MuWebSocket

Called when a pong message is sent from the client.

Specified by:

onPong in interface MuWebSocket

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

public void onError(java.lang.Throwable cause)
             throws java.lang.Exception

Description copied from interface: MuWebSocket

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 MuWebSocket.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 MuWebSocket.onText(String, boolean, DoneCallback) etc (but not onError itself).
• The client sends an invalid frame

Specified by:

onError in interface MuWebSocket

Parameters:

cause - The cause of the error

Throws:

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

session

protected MuWebSocketSession session()

Gets the websocket session

Returns:

A session that can be used to send message and events to the client.

Throws:

java.lang.IllegalStateException - Thrown if the socket has not been connected yet.