Package io.netty.handler.codec.http2

Class Http2MultiplexHandler

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

io.netty.channel.ChannelDuplexHandler

io.netty.handler.codec.http2.Http2ChannelDuplexHandler

io.netty.handler.codec.http2.Http2MultiplexHandler

All Implemented Interfaces:

io.netty.channel.ChannelHandler, io.netty.channel.ChannelInboundHandler, io.netty.channel.ChannelOutboundHandler

public final class Http2MultiplexHandler
extends Http2ChannelDuplexHandler

An HTTP/2 handler that creates child channels for each stream. This handler must be used in combination with Http2FrameCodec.

When a new stream is created, a new Http2StreamChannel is created for it. Applications send and receive Http2StreamFrames on the created channel. ByteBufs cannot be processed by the channel; all writes that reach the head of the pipeline must be an instance of Http2StreamFrame. Writes that reach the head of the pipeline are processed directly by this handler and cannot be intercepted.

The child channel will be notified of user events that impact the stream, such as Http2GoAwayFrame and Http2ResetFrame, as soon as they occur. Although Http2GoAwayFrame and Http2ResetFrame signify that the remote is ignoring further communication, closing of the channel is delayed until any inbound queue is drained with Channel.read(), which follows the default behavior of channels in Netty. Applications are free to close the channel in response to such events if they don't have use for any queued messages. Any connection level events like Http2SettingsFrame and Http2GoAwayFrame will be processed internally and also propagated down the pipeline for other handlers to act on.

Outbound streams are supported via the Http2StreamChannelBootstrap.

ChannelConfig.setMaxMessagesPerRead(int) and ChannelConfig.setAutoRead(boolean) are supported.

Reference Counting

Some Http2StreamFrames implement the ReferenceCounted interface, as they carry reference counted objects (e.g. ByteBufs). The multiplex codec will call ReferenceCounted.retain() before propagating a reference counted object through the pipeline, and thus an application handler needs to release such an object after having consumed it. For more information on reference counting take a look at the reference counted docs.

Channel Events

A child channel becomes active as soon as it is registered to an EventLoop. Therefore, an active channel does not map to an active HTTP/2 stream immediately. Only once a Http2HeadersFrame has been successfully sent or received, does the channel map to an active HTTP/2 stream. In case it is not possible to open a new HTTP/2 stream (i.e. due to the maximum number of active streams being exceeded), the child channel receives an exception indicating the cause and is closed immediately thereafter.

Writability and Flow Control

A child channel observes outbound/remote flow control via the channel's writability. A channel only becomes writable when it maps to an active HTTP/2 stream . A child channel does not know about the connection-level flow control window. ChannelHandlers are free to ignore the channel's writability, in which case the excessive writes will be buffered by the parent channel. It's important to note that only Http2DataFrames are subject to HTTP/2 flow control.

Closing a Http2StreamChannel

Once you close a Http2StreamChannel a Http2ResetFrame will be sent to the remote peer with Http2Error.CANCEL if needed. If you want to close the stream with another Http2Error (due errors / limits) you should propagate a Http2FrameStreamException through the ChannelPipeline. Once it reaches the end of the ChannelPipeline it will automatically close the Http2StreamChannel and send a Http2ResetFrame with the unwrapped Http2Error set. Another possibility is to just directly write a Http2ResetFrame to the Http2StreamChannell.

Nested Class Summary

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

io.netty.channel.ChannelHandler.Sharable

Constructor Summary

Constructors

Constructor	Description
Http2MultiplexHandler(io.netty.channel.ChannelHandler inboundStreamHandler)	Creates a new instance
Http2MultiplexHandler(io.netty.channel.ChannelHandler inboundStreamHandler, io.netty.channel.ChannelHandler upgradeStreamHandler)	Creates a new instance

Method Summary

Modifier and Type	Method	Description
void	channelRead(io.netty.channel.ChannelHandlerContext ctx, Object msg)
void	channelReadComplete(io.netty.channel.ChannelHandlerContext ctx)	Notifies any child streams of the read completion.
void	channelWritabilityChanged(io.netty.channel.ChannelHandlerContext ctx)
void	exceptionCaught(io.netty.channel.ChannelHandlerContext ctx, Throwable cause)
protected void	handlerAdded0(io.netty.channel.ChannelHandlerContext ctx)
protected void	handlerRemoved0(io.netty.channel.ChannelHandlerContext ctx)
void	userEventTriggered(io.netty.channel.ChannelHandlerContext ctx, Object evt)

Methods inherited from class io.netty.handler.codec.http2.Http2ChannelDuplexHandler

forEachActiveStream, handlerAdded, handlerRemoved, newStream

Methods inherited from class io.netty.channel.ChannelDuplexHandler

bind, close, connect, deregister, disconnect, flush, read, write

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelActive, channelInactive, channelRegistered, channelUnregistered

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

ensureNotSharable, isSharable

Methods inherited from class java.lang.Object

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

Constructor Detail

Http2MultiplexHandler

public Http2MultiplexHandler(io.netty.channel.ChannelHandler inboundStreamHandler)

Creates a new instance

Parameters:

inboundStreamHandler - the ChannelHandler that will be added to the ChannelPipeline of the Channels created for new inbound streams.

Http2MultiplexHandler

public Http2MultiplexHandler(io.netty.channel.ChannelHandler inboundStreamHandler,
                             io.netty.channel.ChannelHandler upgradeStreamHandler)

Creates a new instance

Parameters:

inboundStreamHandler - the ChannelHandler that will be added to the ChannelPipeline of the Channels created for new inbound streams.

upgradeStreamHandler - the ChannelHandler that will be added to the ChannelPipeline of the upgraded Channel.

Method Detail

handlerAdded0

protected void handlerAdded0(io.netty.channel.ChannelHandlerContext ctx)

Overrides:

handlerAdded0 in class Http2ChannelDuplexHandler

handlerRemoved0

protected void handlerRemoved0(io.netty.channel.ChannelHandlerContext ctx)

Overrides:

handlerRemoved0 in class Http2ChannelDuplexHandler

channelRead

public void channelRead(io.netty.channel.ChannelHandlerContext ctx,
                        Object msg)
                 throws Exception

Specified by:

channelRead in interface io.netty.channel.ChannelInboundHandler

Overrides:

channelRead in class io.netty.channel.ChannelInboundHandlerAdapter

Throws:

Exception

channelWritabilityChanged

public void channelWritabilityChanged(io.netty.channel.ChannelHandlerContext ctx)
                               throws Exception

Specified by:

channelWritabilityChanged in interface io.netty.channel.ChannelInboundHandler

Overrides:

channelWritabilityChanged in class io.netty.channel.ChannelInboundHandlerAdapter

Throws:

Exception

userEventTriggered

public void userEventTriggered(io.netty.channel.ChannelHandlerContext ctx,
                               Object evt)
                        throws Exception

Specified by:

userEventTriggered in interface io.netty.channel.ChannelInboundHandler

Overrides:

userEventTriggered in class io.netty.channel.ChannelInboundHandlerAdapter

Throws:

Exception

exceptionCaught

public void exceptionCaught(io.netty.channel.ChannelHandlerContext ctx,
                            Throwable cause)
                     throws Exception

Specified by:

exceptionCaught in interface io.netty.channel.ChannelHandler

Specified by:

exceptionCaught in interface io.netty.channel.ChannelInboundHandler

Overrides:

exceptionCaught in class io.netty.channel.ChannelInboundHandlerAdapter

Throws:

Exception

channelReadComplete

public void channelReadComplete(io.netty.channel.ChannelHandlerContext ctx)
                         throws Exception

Notifies any child streams of the read completion.

Specified by:

channelReadComplete in interface io.netty.channel.ChannelInboundHandler

Overrides:

channelReadComplete in class io.netty.channel.ChannelInboundHandlerAdapter

Throws:

Exception