Top Description Inners Fields Constructors Methods
io.netty.handler.codec.http.websocketx

public Class WebSocketClientProtocolHandler

extends WebSocketProtocolHandler
Class Inheritance
Imports
io.netty.channel.ChannelHandlerContext, .ChannelInboundHandler, .ChannelPipeline, io.netty.handler.codec.http.HttpHeaders, java.net.URI, java.util.List
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 ChannelInboundHandler#userEventTriggered(ChannelHandlerContext, Object) and check if the event was of type ClientHandshakeStateEvent#HANDSHAKE_ISSUED or ClientHandshakeStateEvent#HANDSHAKE_COMPLETE.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
WebSocketClientProtocolHandler.ClientHandshakeStateEvent

Events that are fired to notify about handshake status

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(WebSocketClientHandshaker
The WebSocketClientHandshaker which will be used to issue the handshake once the connection was established to the remote peer.
handshaker, 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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
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, long
Handshake timeout in mills, when handshake timeout, will trigger user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
handshakeTimeoutMillis, boolean
true if UTF8 validation of text frames should be enabled
withUTF8Validator)

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT
handshakeTimeoutMillis)

Base constructor

Method Summary

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

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

Returns a WebSocketHandshakeException that depends on which client or server pipeline this handler belongs.
protected void
decode(ChannelHandlerContext
the ChannelHandlerContext which this MessageToMessageDecoder belongs to
ctx, WebSocketFrame
the message to decode to an other one
frame, List<Object>
the List to which decoded messages should be added
out)

Overrides io.netty.handler.codec.http.websocketx.WebSocketProtocolHandler.decode.

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

Overrides io.netty.channel.ChannelHandlerAdapter.handlerAdded.

Implements io.netty.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.netty.handler.codec.http.websocketx.WebSocketProtocolHandler:
bindclosecloseSentconnectderegisterdisconnectexceptionCaughtflushreadwrite

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(WebSocketClientHandshaker handshaker, WebSocketClientProtocolConfig clientConfig)

Base constructor

Parameters
handshaker:WebSocketClientHandshaker

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

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

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

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

withUTF8Validator:boolean

true if UTF8 validation of text frames should be enabled

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 user event ClientHandshakeStateEvent#HANDSHAKE_TIMEOUT

Method Detail

buildHandshakeExceptionback to summary
protected WebSocketClientHandshakeException buildHandshakeException(String message)

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

Doc from io.netty.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
decodeback to summary
protected void decode(ChannelHandlerContext ctx, WebSocketFrame frame, List<Object> out) throws Exception

Overrides io.netty.handler.codec.http.websocketx.WebSocketProtocolHandler.decode.

Doc from io.netty.handler.codec.MessageToMessageDecoder.decode.

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

Parameters
ctx:ChannelHandlerContext

the ChannelHandlerContext which this MessageToMessageDecoder belongs to

frame:WebSocketFrame

the message to decode to an other one

out:List<Object>

the List to which decoded messages should be added

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

Overrides io.netty.channel.ChannelHandlerAdapter.handlerAdded.

Implements io.netty.channel.ChannelHandler.handlerAdded.

Doc from io.netty.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

io.netty.handler.codec.http.websocketx back to summary

public final Enum WebSocketClientProtocolHandler.ClientHandshakeStateEvent

extends Enum<WebSocketClientProtocolHandler.ClientHandshakeStateEvent>
Class Inheritance
Events that are fired to notify about handshake status

Field Summary

Modifier and TypeField and Description
public static final WebSocketClientProtocolHandler.ClientHandshakeStateEvent
HANDSHAKE_COMPLETE

The Handshake was complete successful and so the channel was upgraded to websockets

public static final WebSocketClientProtocolHandler.ClientHandshakeStateEvent
HANDSHAKE_ISSUED

The Handshake was started but the server did not response yet to the request

public static final WebSocketClientProtocolHandler.ClientHandshakeStateEvent
HANDSHAKE_TIMEOUT

The Handshake was timed out

Constructor Summary

AccessConstructor and Description
private
ClientHandshakeStateEvent()

Method Summary

Modifier and TypeMethod and Description
public static WebSocketClientProtocolHandler.ClientHandshakeStateEvent
valueOf(String name)

public static WebSocketClientProtocolHandler.ClientHandshakeStateEvent[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

HANDSHAKE_COMPLETEback to summary
public static final WebSocketClientProtocolHandler.ClientHandshakeStateEvent HANDSHAKE_COMPLETE

The Handshake was complete successful and so the channel was upgraded to websockets

HANDSHAKE_ISSUEDback to summary
public static final WebSocketClientProtocolHandler.ClientHandshakeStateEvent HANDSHAKE_ISSUED

The Handshake was started but the server did not response yet to the request

HANDSHAKE_TIMEOUTback to summary
public static final WebSocketClientProtocolHandler.ClientHandshakeStateEvent HANDSHAKE_TIMEOUT

The Handshake was timed out

Constructor Detail

ClientHandshakeStateEventback to summary
private ClientHandshakeStateEvent()

Method Detail

valueOfback to summary
public static WebSocketClientProtocolHandler.ClientHandshakeStateEvent valueOf(String name)
valuesback to summary
public static WebSocketClientProtocolHandler.ClientHandshakeStateEvent[] values()