MessageAggregator (Netty API Reference (5.0.0.Alpha2))

java.lang.Object
- io.netty.channel.ChannelHandlerAdapter
- - 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

Direct Known Subclasses:

AbstractMemcacheObjectAggregator, HttpObjectAggregator, 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, ChannelHandler.Skip

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

Methods
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 `ChannelHandler` in the `ChannelPipeline`.
`protected abstract long`	`contentLength(S start)` Retrieves the length of the whole content from the specified start message.
`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`	`hasContentLength(S start)` Returns `true` if and only if the specified start message already contains the information about the length of the whole content.
`protected abstract boolean`	`isAggregated(I msg)` Returns `true` if and only if the specified message is already aggregated.
`protected abstract boolean`	`isContentMessage(I msg)` Returns `true` if and only if the specified message is a content message.
`boolean`	`isHandlingOversizedMessage()`
`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.
`int`	`maxCumulationBufferComponents()` Returns the maximum number of components in the cumulation buffer.
`protected abstract Object`	`newContinueResponse(S start)` 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.ChannelHandlerAdapter
bind, channelActive, channelReadComplete, channelRegistered, channelUnregistered, channelWritabilityChanged, close, connect, deregister, disconnect, exceptionCaught, flush, isSharable, read, userEventTriggered, write

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 ChannelHandler 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.
  - 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
```
public final boolean isHandlingOversizedMessage()
```
  - 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 encoder.
    
    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 accour
  - hasContentLength
```
protected abstract boolean hasContentLength(S start)
                                     throws Exception
```
    Returns true if and only if the specified start message already contains the information about the length of the whole content.
    
    Throws:
    
    Exception
  - contentLength
```
protected abstract long contentLength(S start)
                               throws Exception
```
    Retrieves the length of the whole content from the specified start message. This method is invoked only when hasContentLength(Object) returned true.
    
    Throws:
    
    Exception
  - newContinueResponse
```
protected abstract Object newContinueResponse(S start)
                                       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
  - 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
  - channelInactive
```
public void channelInactive(ChannelHandlerContext ctx)
                     throws Exception
```
    Description copied from class: ChannelHandlerAdapter
    
    Calls ChannelHandlerContext.fireChannelInactive() to forward to the next ChannelHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    channelInactive in interface ChannelHandler
    
    Overrides:
    
    channelInactive in class ChannelHandlerAdapter
    
    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

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

Nested Class Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

Methods inherited from class java.lang.Object

Constructor Detail

MessageAggregator

MessageAggregator

Method Detail

acceptInboundMessage

isStartMessage

isContentMessage

isLastContentMessage

isAggregated

maxContentLength

maxCumulationBufferComponents

setMaxCumulationBufferComponents

isHandlingOversizedMessage

ctx

decode

hasContentLength

contentLength

newContinueResponse

beginAggregation

aggregate

finishAggregation

handleOversizedMessage

channelInactive

handlerAdded

handlerRemoved