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

public Class HttpServerUpgradeHandler

extends HttpObjectAggregator
Class Inheritance
Imports
io.netty.buffer.Unpooled, io.netty.channel.ChannelFuture, .ChannelFutureListener, .ChannelHandlerContext, io.netty.util.ReferenceCountUtil, .ReferenceCounted, java.util.ArrayList, .Collection, .List

A server-side handler that receives HTTP requests and optionally performs a protocol switch if the requested protocol is supported. Once an upgrade is performed, this handler removes itself from the pipeline.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
HttpServerUpgradeHandler.SourceCodec

The source codec that is used in the pipeline initially.

public static interface
HttpServerUpgradeHandler.UpgradeCodec

A codec that the source can be upgraded to.

public static interface
HttpServerUpgradeHandler.UpgradeCodecFactory

Creates a new UpgradeCodec for the requested protocol name.

public static class
HttpServerUpgradeHandler.UpgradeEvent

User event that is fired to notify about the completion of an HTTP upgrade to another protocol.

Field Summary

Modifier and TypeField and Description
private boolean
private final HttpHeadersFactory
private final HttpServerUpgradeHandler.SourceCodec
private final HttpHeadersFactory
private final HttpServerUpgradeHandler.UpgradeCodecFactory

Constructor Summary

AccessConstructor and Description
public
HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec
the codec that is being used initially
sourceCodec
,
HttpServerUpgradeHandler.UpgradeCodecFactory
the factory that creates a new upgrade codec for one of the requested upgrade protocols
upgradeCodecFactory
)

Constructs the upgrader with the supported codecs.

public
HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec
the codec that is being used initially
sourceCodec
,
HttpServerUpgradeHandler.UpgradeCodecFactory
the factory that creates a new upgrade codec for one of the requested upgrade protocols
upgradeCodecFactory
,
int
the maximum length of the content of an upgrade request
maxContentLength
)

Constructs the upgrader with the supported codecs.

public
HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec
the codec that is being used initially
sourceCodec
,
HttpServerUpgradeHandler.UpgradeCodecFactory
the factory that creates a new upgrade codec for one of the requested upgrade protocols
upgradeCodecFactory
,
int
the maximum length of the content of an upgrade request
maxContentLength
,
boolean
validate the header names and values of the upgrade response.
validateHeaders
)

Constructs the upgrader with the supported codecs.

public
HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec
the codec that is being used initially
sourceCodec
,
HttpServerUpgradeHandler.UpgradeCodecFactory
the factory that creates a new upgrade codec for one of the requested upgrade protocols
upgradeCodecFactory
,
int
the maximum length of the content of an upgrade request
maxContentLength
,
HttpHeadersFactory
The HttpHeadersFactory to use for headers. The recommended default factory is DefaultHttpHeadersFactory#headersFactory().
headersFactory
,
HttpHeadersFactory
The HttpHeadersFactory to use for trailers. The recommended default factory is DefaultHttpHeadersFactory#trailersFactory().
trailersFactory
)

Constructs the upgrader with the supported codecs.

Method Summary

Modifier and TypeMethod and Description
private FullHttpResponse
createUpgradeResponse(CharSequence upgradeProtocol)

Creates the 101 Switching Protocols response message.

protected void
decode(ChannelHandlerContext ctx, HttpObject
the message to decode to an other one
msg
,
List<Object>
the List to which decoded messages should be added
out
)

Overrides io.netty.handler.codec.MessageAggregator.decode.

Decode from one message to an other.
protected boolean
shouldHandleUpgradeRequest(HttpRequest req)

Determines whether the specified upgrade HttpRequest should be handled by this handler or not.

private static List<CharSequence>
splitHeader(CharSequence header)

Splits a comma-separated header value.

private boolean

Returns:

true if the upgrade occurred, otherwise false.
upgrade
(final ChannelHandlerContext
the context for this handler.
ctx
,
final FullHttpRequest
the HTTP request.
request
)

Attempts to upgrade to the protocol(s) identified by the HttpHeaderNames#UPGRADE header (if provided in the request).

Inherited from io.netty.handler.codec.http.HttpObjectAggregator:
aggregatebeginAggregationcloseAfterContinueResponsefinishAggregationhandleOversizedMessageignoreContentAfterContinueResponseisAggregatedisContentLengthInvalidisContentMessageisLastContentMessageisStartMessagenewContinueResponse

Field Detail

handlingUpgradeback to summary
private boolean handlingUpgrade
headersFactoryback to summary
private final HttpHeadersFactory headersFactory
sourceCodecback to summary
private final HttpServerUpgradeHandler.SourceCodec sourceCodec
trailersFactoryback to summary
private final HttpHeadersFactory trailersFactory
upgradeCodecFactoryback to summary
private final HttpServerUpgradeHandler.UpgradeCodecFactory upgradeCodecFactory

Constructor Detail

HttpServerUpgradeHandlerback to summary
public HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec sourceCodec, HttpServerUpgradeHandler.UpgradeCodecFactory upgradeCodecFactory)

Constructs the upgrader with the supported codecs.

The handler instantiated by this constructor will reject an upgrade request with non-empty content. It should not be a concern because an upgrade request is most likely a GET request. If you have a client that sends a non-GET upgrade request, please consider using HttpServerUpgradeHandler(SourceCodec, UpgradeCodecFactory, int) to specify the maximum length of the content of an upgrade request.

Parameters
sourceCodec:HttpServerUpgradeHandler.SourceCodec

the codec that is being used initially

upgradeCodecFactory:HttpServerUpgradeHandler.UpgradeCodecFactory

the factory that creates a new upgrade codec for one of the requested upgrade protocols

HttpServerUpgradeHandlerback to summary
public HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec sourceCodec, HttpServerUpgradeHandler.UpgradeCodecFactory upgradeCodecFactory, int maxContentLength)

Constructs the upgrader with the supported codecs.

Parameters
sourceCodec:HttpServerUpgradeHandler.SourceCodec

the codec that is being used initially

upgradeCodecFactory:HttpServerUpgradeHandler.UpgradeCodecFactory

the factory that creates a new upgrade codec for one of the requested upgrade protocols

maxContentLength:int

the maximum length of the content of an upgrade request

HttpServerUpgradeHandlerback to summary
public HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec sourceCodec, HttpServerUpgradeHandler.UpgradeCodecFactory upgradeCodecFactory, int maxContentLength, boolean validateHeaders)

Constructs the upgrader with the supported codecs.

Parameters
sourceCodec:HttpServerUpgradeHandler.SourceCodec

the codec that is being used initially

upgradeCodecFactory:HttpServerUpgradeHandler.UpgradeCodecFactory

the factory that creates a new upgrade codec for one of the requested upgrade protocols

maxContentLength:int

the maximum length of the content of an upgrade request

validateHeaders:boolean

validate the header names and values of the upgrade response.

HttpServerUpgradeHandlerback to summary
public HttpServerUpgradeHandler(HttpServerUpgradeHandler.SourceCodec sourceCodec, HttpServerUpgradeHandler.UpgradeCodecFactory upgradeCodecFactory, int maxContentLength, HttpHeadersFactory headersFactory, HttpHeadersFactory trailersFactory)

Constructs the upgrader with the supported codecs.

Parameters
sourceCodec:HttpServerUpgradeHandler.SourceCodec

the codec that is being used initially

upgradeCodecFactory:HttpServerUpgradeHandler.UpgradeCodecFactory

the factory that creates a new upgrade codec for one of the requested upgrade protocols

maxContentLength:int

the maximum length of the content of an upgrade request

headersFactory:HttpHeadersFactory

The HttpHeadersFactory to use for headers. The recommended default factory is DefaultHttpHeadersFactory#headersFactory().

trailersFactory:HttpHeadersFactory

The HttpHeadersFactory to use for trailers. The recommended default factory is DefaultHttpHeadersFactory#trailersFactory().

Method Detail

createUpgradeResponseback to summary
private FullHttpResponse createUpgradeResponse(CharSequence upgradeProtocol)

Creates the 101 Switching Protocols response message.

decodeback to summary
protected void decode(ChannelHandlerContext ctx, HttpObject msg, List<Object> out) throws Exception

Overrides io.netty.handler.codec.MessageAggregator.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

msg:HttpObject

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
shouldHandleUpgradeRequestback to summary
protected boolean shouldHandleUpgradeRequest(HttpRequest req)

Determines whether the specified upgrade HttpRequest should be handled by this handler or not. This method will be invoked only when the request contains an Upgrade header. It always returns true by default, which means any request with an Upgrade header will be handled. You can override this method to ignore certain Upgrade headers, for example:

@Override
protected boolean isUpgradeRequest(HttpRequest req) {
  // Do not handle WebSocket upgrades.
  return !req.headers().contains(HttpHeaderNames.UPGRADE, "websocket", false);
}
splitHeaderback to summary
private static List<CharSequence> splitHeader(CharSequence header)

Splits a comma-separated header value. The returned set is case-insensitive and contains each part with whitespace removed.

upgradeback to summary
private boolean upgrade(final ChannelHandlerContext ctx, final FullHttpRequest request)

Attempts to upgrade to the protocol(s) identified by the HttpHeaderNames#UPGRADE header (if provided in the request).

Parameters
ctx:ChannelHandlerContext

the context for this handler.

request:FullHttpRequest

the HTTP request.

Returns:boolean

true if the upgrade occurred, otherwise false.

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

public Interface HttpServerUpgradeHandler.SourceCodec

Known Direct Implementers
io.netty.handler.codec.http.HttpServerCodec

The source codec that is used in the pipeline initially.

Method Summary

Modifier and TypeMethod and Description
public void
upgradeFrom(ChannelHandlerContext ctx)

Removes this codec (i.e. all associated handlers) from the pipeline.

Method Detail

upgradeFromback to summary
public void upgradeFrom(ChannelHandlerContext ctx)

Removes this codec (i.e. all associated handlers) from the pipeline.

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

public Interface HttpServerUpgradeHandler.UpgradeCodec


A codec that the source can be upgraded to.

Method Summary

Modifier and TypeMethod and Description
public boolean
prepareUpgradeResponse(ChannelHandlerContext ctx, FullHttpRequest upgradeRequest, HttpHeaders upgradeHeaders)

Prepares the upgradeHeaders for a protocol update based upon the contents of upgradeRequest.

public Collection<CharSequence>
requiredUpgradeHeaders()

Gets all protocol-specific headers required by this protocol for a successful upgrade.

public void
upgradeTo(ChannelHandlerContext
the context for the current handler.
ctx
,
FullHttpRequest
the request that triggered the upgrade to this protocol.
upgradeRequest
)

Performs an HTTP protocol upgrade from the source codec.

Method Detail

prepareUpgradeResponseback to summary
public boolean prepareUpgradeResponse(ChannelHandlerContext ctx, FullHttpRequest upgradeRequest, HttpHeaders upgradeHeaders)

Prepares the upgradeHeaders for a protocol update based upon the contents of upgradeRequest. This method returns a boolean value to proceed or abort the upgrade in progress. If false is returned, the upgrade is aborted and the upgradeRequest will be passed through the inbound pipeline as if no upgrade was performed. If true is returned, the upgrade will proceed to the next step which invokes upgradeTo. When returning true, you can add headers to the upgradeHeaders so that they are added to the 101 Switching protocols response.

requiredUpgradeHeadersback to summary
public Collection<CharSequence> requiredUpgradeHeaders()

Gets all protocol-specific headers required by this protocol for a successful upgrade. Any supplied header will be required to appear in the HttpHeaderNames#CONNECTION header as well.

upgradeToback to summary
public void upgradeTo(ChannelHandlerContext ctx, FullHttpRequest upgradeRequest)

Performs an HTTP protocol upgrade from the source codec. This method is responsible for adding all handlers required for the new protocol.

Parameters
ctx:ChannelHandlerContext

the context for the current handler.

upgradeRequest:FullHttpRequest

the request that triggered the upgrade to this protocol.

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

public Interface HttpServerUpgradeHandler.UpgradeCodecFactory


Creates a new UpgradeCodec for the requested protocol name.

Method Summary

Modifier and TypeMethod and Description
public HttpServerUpgradeHandler.UpgradeCodec

Returns:

a new UpgradeCodec, or null if the specified protocol name is not supported
newUpgradeCodec
(CharSequence protocol)

Invoked by HttpServerUpgradeHandler for all the requested protocol names in the order of the client preference.

Method Detail

newUpgradeCodecback to summary
public HttpServerUpgradeHandler.UpgradeCodec newUpgradeCodec(CharSequence protocol)

Invoked by HttpServerUpgradeHandler for all the requested protocol names in the order of the client preference. The first non-null UpgradeCodec returned by this method will be selected.

Returns:HttpServerUpgradeHandler.UpgradeCodec

a new UpgradeCodec, or null if the specified protocol name is not supported

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

public final Class HttpServerUpgradeHandler.UpgradeEvent

extends Object
implements ReferenceCounted
Class Inheritance
  • java.lang.Object
  • io.netty.handler.codec.http.HttpServerUpgradeHandler.UpgradeEvent
All Implemented Interfaces
io.netty.util.ReferenceCounted

User event that is fired to notify about the completion of an HTTP upgrade to another protocol. Contains the original upgrade request so that the response (if required) can be sent using the new protocol.

Field Summary

Modifier and TypeField and Description
private final CharSequence
private final FullHttpRequest

Constructor Summary

AccessConstructor and Description
pack-priv
UpgradeEvent(CharSequence protocol, FullHttpRequest upgradeRequest)

Method Summary

Modifier and TypeMethod and Description
public CharSequence
protocol()

The protocol that the channel has been upgraded to.

public int
refCnt()

Implements io.netty.util.ReferenceCounted.refCnt.

Returns the reference count of this object.
public boolean
release()

Implements io.netty.util.ReferenceCounted.release.

Decreases the reference count by 1 and deallocates this object if the reference count reaches at 0.
public boolean
release(int decrement)

Implements io.netty.util.ReferenceCounted.release.

Decreases the reference count by the specified decrement and deallocates this object if the reference count reaches at 0.
public HttpServerUpgradeHandler.UpgradeEvent
retain()

Implements io.netty.util.ReferenceCounted.retain.

Increases the reference count by 1.
public HttpServerUpgradeHandler.UpgradeEvent
retain(int increment)

Implements io.netty.util.ReferenceCounted.retain.

Increases the reference count by the specified increment.
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public HttpServerUpgradeHandler.UpgradeEvent
touch()

Implements io.netty.util.ReferenceCounted.touch.

Records the current access location of this object for debugging purposes.
public HttpServerUpgradeHandler.UpgradeEvent
touch(Object hint)

Implements io.netty.util.ReferenceCounted.touch.

Records the current access location of this object with an additional arbitrary information for debugging purposes.
public FullHttpRequest
upgradeRequest()

Gets the request that triggered the protocol upgrade.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

protocolback to summary
private final CharSequence protocol
upgradeRequestback to summary
private final FullHttpRequest upgradeRequest

Constructor Detail

UpgradeEventback to summary
pack-priv UpgradeEvent(CharSequence protocol, FullHttpRequest upgradeRequest)

Method Detail

protocolback to summary
public CharSequence protocol()

The protocol that the channel has been upgraded to.

refCntback to summary
public int refCnt()

Implements io.netty.util.ReferenceCounted.refCnt.

Doc from io.netty.util.ReferenceCounted.refCnt.

Returns the reference count of this object. If 0, it means this object has been deallocated.

Annotations
@Override
releaseback to summary
public boolean release()

Implements io.netty.util.ReferenceCounted.release.

Doc from io.netty.util.ReferenceCounted.release.

Decreases the reference count by 1 and deallocates this object if the reference count reaches at 0.

Returns:boolean

true if and only if the reference count became 0 and this object has been deallocated

Annotations
@Override
releaseback to summary
public boolean release(int decrement)

Implements io.netty.util.ReferenceCounted.release.

Doc from io.netty.util.ReferenceCounted.release.

Decreases the reference count by the specified decrement and deallocates this object if the reference count reaches at 0.

Returns:boolean

true if and only if the reference count became 0 and this object has been deallocated

Annotations
@Override
retainback to summary
public HttpServerUpgradeHandler.UpgradeEvent retain()

Implements io.netty.util.ReferenceCounted.retain.

Doc from io.netty.util.ReferenceCounted.retain.

Increases the reference count by 1.

Annotations
@Override
retainback to summary
public HttpServerUpgradeHandler.UpgradeEvent retain(int increment)

Implements io.netty.util.ReferenceCounted.retain.

Doc from io.netty.util.ReferenceCounted.retain.

Increases the reference count by the specified increment.

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
touchback to summary
public HttpServerUpgradeHandler.UpgradeEvent touch()

Implements io.netty.util.ReferenceCounted.touch.

Doc from io.netty.util.ReferenceCounted.touch.

Records the current access location of this object for debugging purposes. If this object is determined to be leaked, the information recorded by this operation will be provided to you via ResourceLeakDetector. This method is a shortcut to touch(null).

Annotations
@Override
touchback to summary
public HttpServerUpgradeHandler.UpgradeEvent touch(Object hint)

Implements io.netty.util.ReferenceCounted.touch.

Doc from io.netty.util.ReferenceCounted.touch.

Records the current access location of this object with an additional arbitrary information for debugging purposes. If this object is determined to be leaked, the information recorded by this operation will be provided to you via ResourceLeakDetector.

Annotations
@Override
upgradeRequestback to summary
public FullHttpRequest upgradeRequest()

Gets the request that triggered the protocol upgrade.