org.jboss.netty.handler.codec.http

## Class HttpMessageDecoder

- java.lang.Object
- - org.jboss.netty.channel.SimpleChannelUpstreamHandler
  - - org.jboss.netty.handler.codec.frame.FrameDecoder
    - - org.jboss.netty.handler.codec.replay.ReplayingDecoder<HttpMessageDecoder.State>
      - - org.jboss.netty.handler.codec.http.HttpMessageDecoder

- All Implemented Interfaces:
    ChannelHandler, ChannelUpstreamHandler, LifeCycleAwareChannelHandler
  Direct Known Subclasses:
    HttpRequestDecoder, HttpResponseDecoder, RtspMessageDecoder

      public abstract class HttpMessageDecoder
      extends ReplayingDecoder<HttpMessageDecoder.State>

  Decodes `ChannelBuffer`s into `HttpMessage`s and `HttpChunk`s.

  ### Parameters that prevents excessive memory consumption

  Name | Meaning
  --- | ---
  `maxInitialLineLength` | The maximum length of the initial line (e.g. `"GET / HTTP/1.0"` or `"HTTP/1.0 200 OK"`) If the length of the initial line exceeds this value, a `TooLongFrameException` will be raised.
  `maxHeaderSize` | The maximum length of all headers. If the sum of the length of each header exceeds this value, a `TooLongFrameException` will be raised.
  `maxChunkSize` | The maximum length of the content or each chunk. If the content length (or the length of each chunk) exceeds this value, the content or chunk will be split into multiple `HttpChunk`s whose length is `maxChunkSize` at maximum.

  ### Chunked Content

  If the content of an HTTP message is greater than `maxChunkSize` or the transfer encoding of the HTTP message is 'chunked', this decoder generates one `HttpMessage` instance and its following `HttpChunk`s per single HTTP message to avoid excessive memory consumption. For example, the following HTTP message:

       GET / HTTP/1.1
       Transfer-Encoding: chunked

       1a
       abcdefghijklmnopqrstuvwxyz
       10
       1234567890abcdef
       0
       Content-MD5: ...
       [blank line]

  triggers `HttpRequestDecoder` to generate 4 objects:
  1. An `HttpRequest` whose `chunked` property is `true`,
  2. The first `HttpChunk` whose content is `'abcdefghijklmnopqrstuvwxyz'`,
  3. The second `HttpChunk` whose content is `'1234567890abcdef'`, and
  4. An `HttpChunkTrailer` which marks the end of the content.
  If you prefer not to handle `HttpChunk`s by yourself for your convenience, insert `HttpChunkAggregator` after this decoder in the `ChannelPipeline`. However, please note that your server might not be as memory efficient as without the aggregator.

  ### Extensibility

  Please note that this decoder is designed to be extended to implement a protocol derived from HTTP, such as RTSP and ICAP. To implement the decoder of such a derived protocol, extend this class and implement all abstract methods properly.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `HttpMessageDecoder.State` The internal state of `HttpMessageDecoder`.

    - ### Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler

      `ChannelHandler.Sharable`

  - ### Field Summary

    - ### Fields inherited from class org.jboss.netty.handler.codec.frame.FrameDecoder

      `cumulation, DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `HttpMessageDecoder()` Creates a new instance with the default `maxInitialLineLength (4096`}, `maxHeaderSize (8192)`, and `maxChunkSize (8192)`.
    `protected` | `HttpMessageDecoder(int maxInitialLineLength, int maxHeaderSize, int maxChunkSize)` Creates a new instance with the specified parameters.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract HttpMessage` | `createMessage(String[] initialLine)`
    `protected Object` | `decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer, HttpMessageDecoder.State state)` Decodes the received packets so far into a frame.
    `protected boolean` | `isContentAlwaysEmpty(HttpMessage msg)`
    `protected abstract boolean` | `isDecodingRequest()`

    - ### Methods inherited from class org.jboss.netty.handler.codec.replay.ReplayingDecoder

      `checkpoint, checkpoint, cleanup, decode, decodeLast, decodeLast, getState, internalBuffer, messageReceived, setState`

    - ### Methods inherited from class org.jboss.netty.handler.codec.frame.FrameDecoder

      `actualReadableBytes, afterAdd, afterRemove, appendToCumulation, beforeAdd, beforeRemove, channelClosed, channelDisconnected, exceptionCaught, getMaxCumulationBufferCapacity, getMaxCumulationBufferComponents, isUnfold, newCumulationBuffer, replace, setMaxCumulationBufferCapacity, setMaxCumulationBufferComponents, setUnfold, unfoldAndFireMessageReceived, updateCumulation`

    - ### Methods inherited from class org.jboss.netty.channel.SimpleChannelUpstreamHandler

      `channelBound, channelConnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### HttpMessageDecoder

          protected HttpMessageDecoder()

      Creates a new instance with the default `maxInitialLineLength (4096`}, `maxHeaderSize (8192)`, and `maxChunkSize (8192)`.

    - #### HttpMessageDecoder

          protected HttpMessageDecoder(int maxInitialLineLength,
                            int maxHeaderSize,
                            int maxChunkSize)

      Creates a new instance with the specified parameters.

  - ### Method Detail

    - #### decode

          protected Object decode(ChannelHandlerContext ctx,
                      Channel channel,
                      ChannelBuffer buffer,
                      HttpMessageDecoder.State state)
                           throws Exception

      Description copied from class: `ReplayingDecoder`
      Decodes the received packets so far into a frame.
      Specified by:
        `decode` in class `ReplayingDecoder<HttpMessageDecoder.State>`
      Parameters:
        `ctx` - the context of this handler
        `channel` - the current channel
        `buffer` - the cumulative buffer of received packets so far. Note that the buffer might be empty, which means you should not make an assumption that the buffer contains at least one byte in your decoder implementation.
        `state` - the current decoder state (`null` if unused)
      Returns:
        the decoded frame
      Throws:
        `Exception`

    - #### isContentAlwaysEmpty

          protected boolean isContentAlwaysEmpty(HttpMessage msg)

    - #### isDecodingRequest

          protected abstract boolean isDecodingRequest()

    - #### createMessage

          protected abstract HttpMessage createMessage(String[] initialLine)
                                                throws Exception

      Throws:
        `Exception`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.