io.netty.handler.codec

Class MessageAggregator<I,S,C extends ByteBufHolder,O extends ByteBufHolder>

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

io.netty.handler.codec.MessageToMessageDecoder<I>

io.netty.handler.codec.MessageAggregator<I,S,C,O>

Type Parameters:

I - the type that covers both start message and content message

S - the type of the start message

C - the type of the content message (must be a subtype of ByteBufHolder)

O - the type of the aggregated message (must be a subtype of S and ByteBufHolder)

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler

Direct Known Subclasses:

AbstractMemcacheObjectAggregator, HttpObjectAggregator, RedisBulkStringAggregator, StompSubframeAggregator, WebSocketFrameAggregator

public abstract class MessageAggregator<I,S,C extends ByteBufHolder,O extends ByteBufHolder>
extends MessageToMessageDecoder<I>

An abstract ChannelHandler that aggregates a series of message objects into a single aggregated message.

'A series of messages' is composed of the following:

• a single start message which optionally contains the first part of the content, and
• 1 or more content messages.

The content of the aggregated message will be the merged content of the start message and its following content messages. If this aggregator encounters a content message where isLastContentMessage(ByteBufHolder) return true for, the aggregator will finish the aggregation and produce the aggregated message and expect another start message.

Nested Class Summary

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

ChannelHandler.Sharable

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MessageAggregator(int maxContentLength) Creates a new instance.
protected	MessageAggregator(int maxContentLength, Class<? extends I> inboundMessageType)

Method Summary

Modifier and Type	Method and Description
boolean	acceptInboundMessage(Object msg) Returns true if the given message should be handled.
protected void	aggregate(O aggregated, C content) Transfers the information provided by the specified content message to the specified aggregated message.
protected abstract O	beginAggregation(S start, ByteBuf content) Creates a new aggregated message from the specified start message and the specified content.
void	channelInactive(ChannelHandlerContext ctx) Calls ChannelHandlerContext.fireChannelInactive() to forward to the next ChannelInboundHandler in the ChannelPipeline.
void	channelReadComplete(ChannelHandlerContext ctx) Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline.
protected abstract boolean	closeAfterContinueResponse(Object msg) Determine if the channel should be closed after the result of newContinueResponse(Object, int, ChannelPipeline) is written.
protected ChannelHandlerContext	ctx()
protected void	decode(ChannelHandlerContext ctx, I msg, List<Object> out) Decode from one message to an other.
protected void	finishAggregation(O aggregated) Invoked when the specified aggregated message is about to be passed to the next handler in the pipeline.
protected void	handleOversizedMessage(ChannelHandlerContext ctx, S oversized) Invoked when an incoming request exceeds the maximum content length.
void	handlerAdded(ChannelHandlerContext ctx) Do nothing by default, sub-classes may override this method.
void	handlerRemoved(ChannelHandlerContext ctx) Do nothing by default, sub-classes may override this method.
protected abstract boolean	ignoreContentAfterContinueResponse(Object msg) Determine if all objects for the current request/response should be ignored or not.
protected abstract boolean	isAggregated(I msg) Returns true if and only if the specified message is already aggregated.
protected abstract boolean	isContentLengthInvalid(S start, int maxContentLength) Determine if the message start's content length is known, and if it greater than maxContentLength.
protected abstract boolean	isContentMessage(I msg) Returns true if and only if the specified message is a content message.
boolean	isHandlingOversizedMessage() Deprecated. This method will be removed in future releases.
protected abstract boolean	isLastContentMessage(C msg) Returns true if and only if the specified message is the last content message.
protected abstract boolean	isStartMessage(I msg) Returns true if and only if the specified message is a start message.
int	maxContentLength() Returns the maximum allowed length of the aggregated message in bytes.
int	maxCumulationBufferComponents() Returns the maximum number of components in the cumulation buffer.
protected abstract Object	newContinueResponse(S start, int maxContentLength, ChannelPipeline pipeline) Returns the 'continue response' for the specified start message if necessary.
void	setMaxCumulationBufferComponents(int maxCumulationBufferComponents) Sets the maximum number of components in the cumulation buffer.

Methods inherited from class io.netty.handler.codec.MessageToMessageDecoder

channelRead

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelActive, channelRegistered, channelUnregistered, channelWritabilityChanged, exceptionCaught, userEventTriggered

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

MessageAggregator

protected MessageAggregator(int maxContentLength)

Creates a new instance.

Parameters:

maxContentLength - the maximum length of the aggregated content. If the length of the aggregated content exceeds this value, handleOversizedMessage(ChannelHandlerContext, Object) will be called.

MessageAggregator

protected MessageAggregator(int maxContentLength,
                            Class<? extends I> inboundMessageType)

Method Detail

acceptInboundMessage

public boolean acceptInboundMessage(Object msg)
                             throws Exception

Description copied from class: MessageToMessageDecoder

Returns true if the given message should be handled. If false it will be passed to the next ChannelInboundHandler in the ChannelPipeline.

Overrides:

acceptInboundMessage in class MessageToMessageDecoder<I>

Throws:

Exception

isStartMessage

protected abstract boolean isStartMessage(I msg)
                                   throws Exception

Returns true if and only if the specified message is a start message. Typically, this method is implemented as a single return statement with instanceof:

 return msg instanceof MyStartMessage;
 

Throws:

Exception

isContentMessage

protected abstract boolean isContentMessage(I msg)
                                     throws Exception

Returns true if and only if the specified message is a content message. Typically, this method is implemented as a single return statement with instanceof:

 return msg instanceof MyContentMessage;
 

Throws:

Exception

isLastContentMessage

protected abstract boolean isLastContentMessage(C msg)
                                         throws Exception

Returns true if and only if the specified message is the last content message. Typically, this method is implemented as a single return statement with instanceof:

 return msg instanceof MyLastContentMessage;
 

or with instanceof and boolean field check:

 return msg instanceof MyContentMessage && msg.isLastFragment();
 

Throws:

Exception

isAggregated

protected abstract boolean isAggregated(I msg)
                                 throws Exception

Returns true if and only if the specified message is already aggregated. If this method returns true, this handler will simply forward the message to the next handler as-is.

Throws:

Exception

maxContentLength

public final int maxContentLength()

Returns the maximum allowed length of the aggregated message in bytes.

maxCumulationBufferComponents

public final int maxCumulationBufferComponents()

Returns the maximum number of components in the cumulation buffer. If the number of the components in the cumulation buffer exceeds this value, the components of the cumulation buffer are consolidated into a single component, involving memory copies. The default value of this property is .

setMaxCumulationBufferComponents

public final void setMaxCumulationBufferComponents(int maxCumulationBufferComponents)

Sets the maximum number of components in the cumulation buffer. If the number of the components in the cumulation buffer exceeds this value, the components of the cumulation buffer are consolidated into a single component, involving memory copies. The default value of this property is and its minimum allowed value is 2.

isHandlingOversizedMessage

@Deprecated
public final boolean isHandlingOversizedMessage()

Deprecated. This method will be removed in future releases.

ctx

protected final ChannelHandlerContext ctx()

decode

protected void decode(ChannelHandlerContext ctx,
                      I msg,
                      List<Object> out)
               throws Exception

Description copied from class: MessageToMessageDecoder

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

Specified by:

decode in class MessageToMessageDecoder<I>

Parameters:

ctx - the ChannelHandlerContext which this MessageToMessageDecoder belongs to

msg - the message to decode to an other one

out - the List to which decoded messages should be added

Throws:

Exception - is thrown if an error occurs

isContentLengthInvalid

protected abstract boolean isContentLengthInvalid(S start,
                                                  int maxContentLength)
                                           throws Exception

Determine if the message start's content length is known, and if it greater than maxContentLength.

Parameters:

start - The message which may indicate the content length.

maxContentLength - The maximum allowed content length.

Returns:

true if the message start's content length is known, and if it greater than maxContentLength. false otherwise.

Throws:

Exception

newContinueResponse

protected abstract Object newContinueResponse(S start,
                                              int maxContentLength,
                                              ChannelPipeline pipeline)
                                       throws Exception

Returns the 'continue response' for the specified start message if necessary. For example, this method is useful to handle an HTTP 100-continue header.

Returns:

the 'continue response', or null if there's no message to send

Throws:

Exception

closeAfterContinueResponse

protected abstract boolean closeAfterContinueResponse(Object msg)
                                               throws Exception

Determine if the channel should be closed after the result of newContinueResponse(Object, int, ChannelPipeline) is written.

Parameters:

msg - The return value from newContinueResponse(Object, int, ChannelPipeline).

Returns:

true if the channel should be closed after the result of newContinueResponse(Object, int, ChannelPipeline) is written. false otherwise.

Throws:

Exception

ignoreContentAfterContinueResponse

protected abstract boolean ignoreContentAfterContinueResponse(Object msg)
                                                       throws Exception

Determine if all objects for the current request/response should be ignored or not. Messages will stop being ignored the next time isContentMessage(Object) returns true.

Parameters:

msg - The return value from newContinueResponse(Object, int, ChannelPipeline).

Returns:

true if all objects for the current request/response should be ignored or not. false otherwise.

Throws:

Exception

beginAggregation

protected abstract O beginAggregation(S start,
                                      ByteBuf content)
                               throws Exception

Creates a new aggregated message from the specified start message and the specified content. If the start message implements ByteBufHolder, its content is appended to the specified content. This aggregator will continue to append the received content to the specified content.

Throws:

Exception

aggregate

protected void aggregate(O aggregated,
                         C content)
                  throws Exception

Transfers the information provided by the specified content message to the specified aggregated message. Note that the content of the specified content message has been appended to the content of the specified aggregated message already, so that you don't need to. Use this method to transfer the additional information that the content message provides to aggregated.

Throws:

Exception

finishAggregation

protected void finishAggregation(O aggregated)
                          throws Exception

Invoked when the specified aggregated message is about to be passed to the next handler in the pipeline.

Throws:

Exception

handleOversizedMessage

protected void handleOversizedMessage(ChannelHandlerContext ctx,
                                      S oversized)
                               throws Exception

Invoked when an incoming request exceeds the maximum content length. The default behvaior is to trigger an exceptionCaught() event with a TooLongFrameException.

Parameters:

ctx - the ChannelHandlerContext

oversized - the accumulated message up to this point, whose type is S or O

Throws:

Exception

channelReadComplete

public void channelReadComplete(ChannelHandlerContext ctx)
                         throws Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelReadComplete in interface ChannelInboundHandler

Overrides:

channelReadComplete in class MessageToMessageDecoder<I>

Throws:

Exception

channelInactive

public void channelInactive(ChannelHandlerContext ctx)
                     throws Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelInactive() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelInactive in interface ChannelInboundHandler

Overrides:

channelInactive in class ChannelInboundHandlerAdapter

Throws:

Exception

handlerAdded

public void handlerAdded(ChannelHandlerContext ctx)
                  throws Exception

Description copied from class: ChannelHandlerAdapter

Do nothing by default, sub-classes may override this method.

Specified by:

handlerAdded in interface ChannelHandler

Overrides:

handlerAdded in class ChannelHandlerAdapter

Throws:

Exception

handlerRemoved

public void handlerRemoved(ChannelHandlerContext ctx)
                    throws Exception

Description copied from class: ChannelHandlerAdapter

Do nothing by default, sub-classes may override this method.

Specified by:

handlerRemoved in interface ChannelHandler

Overrides:

handlerRemoved in class ChannelHandlerAdapter

Throws:

Exception