Top Description Fields Constructors Methods
io.netty5.handler.codec.http.websocketx

public Class WebSocketClientProtocolHandler

extends WebSocketProtocolHandler
Class Inheritance
Imports
io.netty5.channel.ChannelHandler, .ChannelHandlerContext, .ChannelPipeline, io.netty5.handler.codec.http.headers.HttpHeaders, io.netty5.util.Resource, java.net.URI, java.util.Objects
This handler does all the heavy lifting for you to run a websocket client. It takes care of websocket handshaking as well as processing of Ping, Pong frames. Text and Binary data frames are passed to the next handler in the pipeline (implemented by you) for processing. Also the close frame is passed to the next handler as you may want inspect it before close the connection if the handleCloseFrames is false, default is true. This implementation will establish the websocket connection once the connection to the remote server was complete. To know once a handshake was done you can intercept the ChannelHandler#channelInboundEvent(ChannelHandlerContext, Object) and check if the event was of type WebSocketHandshakeCompletionEvent.

Field Summary

Modifier and TypeField and Description
private final WebSocketClientProtocolConfig
clientConfig

private final WebSocketClientHandshaker
handshaker

Constructor Summary

AccessConstructor and Description
public
WebSocketClientProtocolHandler(WebSocketClientProtocolConfig
Client protocol configuration.
clientConfig)

Base constructor

public
WebSocketClientProtocolHandler(URI
URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.
webSocketURL, WebSocketVersion
Version of web socket specification to use to connect to the server
version, String
Sub protocol request sent to the server.
subprotocol, boolean allowExtensions, HttpHeaders
Map of custom headers to add to the client request
customHeaders, int
Maximum length of a frame's payload
maxFramePayloadLength, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames, boolean
Whether to mask all written websocket frames. This must be set to true in order to be fully compatible with the websocket specifications. Client applications that communicate with a non-standard server which doesn't require masking might set this to false to achieve a higher performance.
performMasking, boolean
When set to true, frames which are not masked properly according to the standard will still be accepted.
allowMaskMismatch)

Base constructor

public
WebSocketClientProtocolHandler(URI
URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.
webSocketURL, WebSocketVersion
Version of web socket specification to use to connect to the server
version, String
Sub protocol request sent to the server.
subprotocol, boolean allowExtensions, HttpHeaders
Map of custom headers to add to the client request
customHeaders, int
Maximum length of a frame's payload
maxFramePayloadLength, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames, boolean
Whether to mask all written websocket frames. This must be set to true in order to be fully compatible with the websocket specifications. Client applications that communicate with a non-standard server which doesn't require masking might set this to false to achieve a higher performance.
performMasking, boolean
When set to true, frames which are not masked properly according to the standard will still be accepted.
allowMaskMismatch, long
Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.
handshakeTimeoutMillis)

Base constructor

public
WebSocketClientProtocolHandler(URI
URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.
webSocketURL, WebSocketVersion
Version of web socket specification to use to connect to the server
version, String
Sub protocol request sent to the server.
subprotocol, boolean allowExtensions, HttpHeaders
Map of custom headers to add to the client request
customHeaders, int
Maximum length of a frame's payload
maxFramePayloadLength, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames)

Base constructor

public
WebSocketClientProtocolHandler(URI
URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.
webSocketURL, WebSocketVersion
Version of web socket specification to use to connect to the server
version, String
Sub protocol request sent to the server.
subprotocol, boolean allowExtensions, HttpHeaders
Map of custom headers to add to the client request
customHeaders, int
Maximum length of a frame's payload
maxFramePayloadLength, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames, long
Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.
handshakeTimeoutMillis)

Base constructor

public
WebSocketClientProtocolHandler(URI
URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.
webSocketURL, WebSocketVersion
Version of web socket specification to use to connect to the server
version, String
Sub protocol request sent to the server.
subprotocol, boolean allowExtensions, HttpHeaders
Map of custom headers to add to the client request
customHeaders, int
Maximum length of a frame's payload
maxFramePayloadLength)

Base constructor

public
WebSocketClientProtocolHandler(URI
URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.
webSocketURL, WebSocketVersion
Version of web socket specification to use to connect to the server
version, String
Sub protocol request sent to the server.
subprotocol, boolean allowExtensions, HttpHeaders
Map of custom headers to add to the client request
customHeaders, int
Maximum length of a frame's payload
maxFramePayloadLength, long
Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.
handshakeTimeoutMillis)

Base constructor

public
WebSocketClientProtocolHandler(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames)

Base constructor

public
WebSocketClientProtocolHandler(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames, long
Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.
handshakeTimeoutMillis)

Base constructor

public
WebSocketClientProtocolHandler(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames, boolean
true if pong frames should not be forwarded
dropPongFrames)

Base constructor

public
WebSocketClientProtocolHandler(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker, boolean
true if close frames should not be forwarded and just close the channel
handleCloseFrames, boolean
true if pong frames should not be forwarded
dropPongFrames, long
Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.
handshakeTimeoutMillis)

Base constructor

public
WebSocketClientProtocolHandler(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker)

Base constructor

public
WebSocketClientProtocolHandler(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker, long
Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.
handshakeTimeoutMillis)

Base constructor

Method Summary

Modifier and TypeMethod and Description
protected WebSocketClientHandshakeException
buildHandshakeException(String message)

Overrides io.netty5.handler.codec.http.websocketx.WebSocketProtocolHandler.buildHandshakeException.

Returns a WebSocketHandshakeException that depends on which client or server pipeline this handler belongs.
protected void
decodeAndClose(ChannelHandlerContext
the ChannelHandlerContext which this MessageToMessageDecoder belongs to
ctx, WebSocketFrame
the message to decode to another one
frame)

Overrides io.netty5.handler.codec.http.websocketx.WebSocketProtocolHandler.decodeAndClose.

Decode from one message to another.
public void
handlerAdded(ChannelHandlerContext ctx)

Overrides default io.netty5.channel.ChannelHandler.handlerAdded.

Gets called after the ChannelHandler was added to the actual context and it's ready to handle events.
public WebSocketClientHandshaker
handshaker()

Returns the used handshaker

Inherited from io.netty5.handler.codec.http.websocketx.WebSocketProtocolHandler:
channelExceptionCaughtclosecloseSentdecodewrite

Field Detail

clientConfigback to summary
private final WebSocketClientProtocolConfig clientConfig
handshakerback to summary
private final WebSocketClientHandshaker handshaker

Constructor Detail

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientProtocolConfig clientConfig)

Base constructor

Parameters
clientConfig:WebSocketClientProtocolConfig

Client protocol configuration.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol, boolean allowExtensions, HttpHeaders customHeaders, int maxFramePayloadLength, boolean handleCloseFrames, boolean performMasking, boolean allowMaskMismatch)

Base constructor

Parameters
webSocketURL:URI

URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.

version:WebSocketVersion

Version of web socket specification to use to connect to the server

subprotocol:String

Sub protocol request sent to the server.

customHeaders:HttpHeaders

Map of custom headers to add to the client request

maxFramePayloadLength:int

Maximum length of a frame's payload

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

performMasking:boolean

Whether to mask all written websocket frames. This must be set to true in order to be fully compatible with the websocket specifications. Client applications that communicate with a non-standard server which doesn't require masking might set this to false to achieve a higher performance.

allowMaskMismatch:boolean

When set to true, frames which are not masked properly according to the standard will still be accepted.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol, boolean allowExtensions, HttpHeaders customHeaders, int maxFramePayloadLength, boolean handleCloseFrames, boolean performMasking, boolean allowMaskMismatch, long handshakeTimeoutMillis)

Base constructor

Parameters
webSocketURL:URI

URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.

version:WebSocketVersion

Version of web socket specification to use to connect to the server

subprotocol:String

Sub protocol request sent to the server.

customHeaders:HttpHeaders

Map of custom headers to add to the client request

maxFramePayloadLength:int

Maximum length of a frame's payload

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

performMasking:boolean

Whether to mask all written websocket frames. This must be set to true in order to be fully compatible with the websocket specifications. Client applications that communicate with a non-standard server which doesn't require masking might set this to false to achieve a higher performance.

allowMaskMismatch:boolean

When set to true, frames which are not masked properly according to the standard will still be accepted.

handshakeTimeoutMillis:long

Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol, boolean allowExtensions, HttpHeaders customHeaders, int maxFramePayloadLength, boolean handleCloseFrames)

Base constructor

Parameters
webSocketURL:URI

URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.

version:WebSocketVersion

Version of web socket specification to use to connect to the server

subprotocol:String

Sub protocol request sent to the server.

customHeaders:HttpHeaders

Map of custom headers to add to the client request

maxFramePayloadLength:int

Maximum length of a frame's payload

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol, boolean allowExtensions, HttpHeaders customHeaders, int maxFramePayloadLength, boolean handleCloseFrames, long handshakeTimeoutMillis)

Base constructor

Parameters
webSocketURL:URI

URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.

version:WebSocketVersion

Version of web socket specification to use to connect to the server

subprotocol:String

Sub protocol request sent to the server.

customHeaders:HttpHeaders

Map of custom headers to add to the client request

maxFramePayloadLength:int

Maximum length of a frame's payload

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

handshakeTimeoutMillis:long

Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol, boolean allowExtensions, HttpHeaders customHeaders, int maxFramePayloadLength)

Base constructor

Parameters
webSocketURL:URI

URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.

version:WebSocketVersion

Version of web socket specification to use to connect to the server

subprotocol:String

Sub protocol request sent to the server.

customHeaders:HttpHeaders

Map of custom headers to add to the client request

maxFramePayloadLength:int

Maximum length of a frame's payload

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol, boolean allowExtensions, HttpHeaders customHeaders, int maxFramePayloadLength, long handshakeTimeoutMillis)

Base constructor

Parameters
webSocketURL:URI

URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be sent to this URL.

version:WebSocketVersion

Version of web socket specification to use to connect to the server

subprotocol:String

Sub protocol request sent to the server.

customHeaders:HttpHeaders

Map of custom headers to add to the client request

maxFramePayloadLength:int

Maximum length of a frame's payload

handshakeTimeoutMillis:long

Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker, boolean handleCloseFrames)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker, boolean handleCloseFrames, long handshakeTimeoutMillis)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

handshakeTimeoutMillis:long

Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker, boolean handleCloseFrames, boolean dropPongFrames)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

dropPongFrames:boolean

true if pong frames should not be forwarded

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker, boolean handleCloseFrames, boolean dropPongFrames, long handshakeTimeoutMillis)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.

handleCloseFrames:boolean

true if close frames should not be forwarded and just close the channel

dropPongFrames:boolean

true if pong frames should not be forwarded

handshakeTimeoutMillis:long

Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.

WebSocketClientProtocolHandlerback to summary
public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker, long handshakeTimeoutMillis)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.

handshakeTimeoutMillis:long

Handshake timeout in mills, when handshake timeout, will trigger an inbound channel event WebSocketClientHandshakeCompletionEvent with a WebSocketHandshakeTimeoutException.

Method Detail

buildHandshakeExceptionback to summary
protected WebSocketClientHandshakeException buildHandshakeException(String message)

Overrides io.netty5.handler.codec.http.websocketx.WebSocketProtocolHandler.buildHandshakeException.

Doc from io.netty5.handler.codec.http.websocketx.WebSocketProtocolHandler.buildHandshakeException.

Returns a WebSocketHandshakeException that depends on which client or server pipeline this handler belongs. Should be overridden in implementation otherwise a default exception is used.

Annotations
@Override
decodeAndCloseback to summary
protected void decodeAndClose(ChannelHandlerContext ctx, WebSocketFrame frame) throws Exception

Overrides io.netty5.handler.codec.http.websocketx.WebSocketProtocolHandler.decodeAndClose.

Doc from io.netty5.handler.codec.MessageToMessageDecoder.decodeAndClose.

Decode from one message to another. This method will be called for each written message that can be handled by this decoder.

The message will not be automatically disposed of after this call. Instead, the responsibility of ensuring that messages are disposed of falls upon the implementor of this method.

Subclasses that wish to have incoming messages automatically disposed of should instead override the decodeAndClose(ChannelHandlerContext, Object) method.

Parameters
ctx:ChannelHandlerContext

the ChannelHandlerContext which this MessageToMessageDecoder belongs to

frame:WebSocketFrame

the message to decode to another one

Annotations
@Override
Exceptions
Exception:
is thrown if an error occurs
handlerAddedback to summary
public void handlerAdded(ChannelHandlerContext ctx)

Overrides default io.netty5.channel.ChannelHandler.handlerAdded.

Doc from io.netty5.channel.ChannelHandler.handlerAdded.

Gets called after the ChannelHandler was added to the actual context and it's ready to handle events.

Annotations
@Override
handshakerback to summary
public WebSocketClientHandshaker handshaker()

Returns the used handshaker