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

public Class HttpServerUpgradeHandler<C extends io.netty5.handler.codec.http.HttpContent<C>>

extends HttpObjectAggregator<C extends HttpContent<C>>
Class Inheritance
Imports
io.netty5.buffer.BufferAllocator, io.netty5.channel.internal.DelegatingChannelHandlerContext, io.netty5.handler.codec.http.headers.HttpHeaders, io.netty5.util.Resource, .Send, io.netty5.channel.ChannelFutureListeners, .ChannelHandlerContext, io.netty5.util.concurrent.Future, java.util.ArrayList, .Collection, .Iterator, .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
handlingUpgrade

private final HttpServerUpgradeHandler.SourceCodec
sourceCodec

private final HttpServerUpgradeHandler.UpgradeCodecFactory
upgradeCodecFactory

private final boolean
validateHeaders

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.

Method Summary

Modifier and TypeMethod and Description
private FullHttpResponse
createUpgradeResponse(BufferAllocator allocator, CharSequence upgradeProtocol)

Creates the 101 Switching Protocols response message.

protected void
decodeAndClose(final ChannelHandlerContext
the ChannelHandlerContext which this MessageToMessageDecoder belongs to
ctx, HttpObject
the message to decode to another one
msg)

Overrides io.netty5.handler.codec.MessageToMessageDecoder.decodeAndClose.

Decode from one message to another.
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 void
tryUpgrade(ChannelHandlerContext ctx, FullHttpRequest request)

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.netty5.handler.codec.http.HttpObjectAggregator:
aggregatebeginAggregationchannelExceptionCaughtcloseAfterContinueResponsefinishAggregationhandleOversizedMessageignoreContentAfterContinueResponseisAggregatedisContentLengthInvalidisLastContentMessagelengthForAggregationlengthForContentnewContinueResponsetryContentMessagetryStartMessage

Field Detail

handlingUpgradeback to summary
private boolean handlingUpgrade
sourceCodecback to summary
private final HttpServerUpgradeHandler.SourceCodec sourceCodec
upgradeCodecFactoryback to summary
private final HttpServerUpgradeHandler.UpgradeCodecFactory upgradeCodecFactory
validateHeadersback to summary
private final boolean validateHeaders

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.

Method Detail

createUpgradeResponseback to summary
private FullHttpResponse createUpgradeResponse(BufferAllocator allocator, CharSequence upgradeProtocol)

Creates the 101 Switching Protocols response message.

decodeAndCloseback to summary
protected void decodeAndClose(final ChannelHandlerContext ctx, HttpObject msg) throws Exception

Overrides io.netty5.handler.codec.MessageToMessageDecoder.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

msg:HttpObject

the message to decode to another one

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.

tryUpgradeback to summary
private void tryUpgrade(ChannelHandlerContext ctx, FullHttpRequest request)
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.netty5.handler.codec.http back to summary

public Interface HttpServerUpgradeHandler.SourceCodec

Known Direct Implementers
io.netty5.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.netty5.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.netty5.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.netty5.handler.codec.http back to summary

public final Class HttpServerUpgradeHandler.UpgradeEvent

extends Object
implements Resource<HttpServerUpgradeHandler.UpgradeEvent>
Class Inheritance
  • java.lang.Object
  • io.netty5.handler.codec.http.HttpServerUpgradeHandler.UpgradeEvent
All Implemented Interfaces
io.netty5.util.Resource, java.lang.AutoCloseable
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
protocol

private final FullHttpRequest
upgradeRequest

Constructor Summary

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

Method Summary

Modifier and TypeMethod and Description
public void
close()

Implements io.netty5.util.Resource.close.

Close the resource, making it inaccessible.
public HttpServerUpgradeHandler.UpgradeEvent
copy()

public boolean
isAccessible()

Implements io.netty5.util.Resource.isAccessible.

Check if this object is accessible.
public CharSequence
protocol()

The protocol that the channel has been upgraded to.

public Send<HttpServerUpgradeHandler.UpgradeEvent>
send()

Implements io.netty5.util.Resource.send.

Send this object instance to another Thread, transferring the ownership to the recipient.
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public HttpServerUpgradeHandler.UpgradeEvent
touch(Object
An optional hint about this access and its context. May be null.
hint)

Overrides default io.netty5.util.Resource.touch.

Record the current access location 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

closeback to summary
public void close()

Implements io.netty5.util.Resource.close.

Doc from io.netty5.util.Resource.close.

Close the resource, making it inaccessible.

Note, this method is not thread-safe unless otherwise specified.

Annotations
@Override
copyback to summary
public HttpServerUpgradeHandler.UpgradeEvent copy()
isAccessibleback to summary
public boolean isAccessible()

Implements io.netty5.util.Resource.isAccessible.

Doc from io.netty5.util.Resource.isAccessible.

Check if this object is accessible.

Returns:boolean

true if this object is still valid and can be accessed, otherwise false if, for instance, this object has been dropped/deallocated, or been sent elsewhere.

Annotations
@Override
protocolback to summary
public CharSequence protocol()

The protocol that the channel has been upgraded to.

sendback to summary
public Send<HttpServerUpgradeHandler.UpgradeEvent> send()

Implements io.netty5.util.Resource.send.

Doc from io.netty5.util.Resource.send.

Send this object instance to another Thread, transferring the ownership to the recipient.

The object must be in a state where it can be sent, which includes at least being accessible.

When sent, this instance will immediately become inaccessible, as if by closing it. All attempts at accessing an object that has been sent, even if that object has not yet been received, should cause an exception to be thrown.

Calling close() on an object that has been sent will have no effect, so this method is safe to call within a try-with-resources statement.

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(Object hint)

Overrides default io.netty5.util.Resource.touch.

Doc from io.netty5.util.Resource.touch.

Record the current access location for debugging purposes. This information may be included if the resource throws a life-cycle related exception, or if it leaks. If this resource has already been closed, then this method has no effect.

Parameters
hint:Object

An optional hint about this access and its context. May be null.

Returns:HttpServerUpgradeHandler.UpgradeEvent

This resource instance.

Annotations
@Override
upgradeRequestback to summary
public FullHttpRequest upgradeRequest()

Gets the request that triggered the protocol upgrade.