org.jboss.netty.handler.codec.frame

## Class DelimiterBasedFrameDecoder

- java.lang.Object
- - org.jboss.netty.channel.SimpleChannelUpstreamHandler
  - - org.jboss.netty.handler.codec.frame.FrameDecoder
    - - org.jboss.netty.handler.codec.frame.DelimiterBasedFrameDecoder

- All Implemented Interfaces:
    ChannelHandler, ChannelUpstreamHandler, LifeCycleAwareChannelHandler

      public class DelimiterBasedFrameDecoder
      extends FrameDecoder

  A decoder that splits the received `ChannelBuffer`s by one or more delimiters. It is particularly useful for decoding the frames which ends with a delimiter such as `NUL` or newline characters.

  ### Predefined delimiters

  `Delimiters` defines frequently used delimiters for convenience' sake.

  ### Specifying more than one delimiter

  `DelimiterBasedFrameDecoder` allows you to specify more than one delimiter. If more than one delimiter is found in the buffer, it chooses the delimiter which produces the shortest frame. For example, if you have the following data in the buffer:

       +--------------+
       | ABC\nDEF\r\n |
       +--------------+

  a `DelimiterBasedFrameDecoder``(``Delimiters.lineDelimiter()``)` will choose `'\n'` as the first delimiter and produce two frames:

       +-----+-----+
       | ABC | DEF |
       +-----+-----+

  rather than incorrectly choosing `'\r\n'` as the first delimiter:

       +----------+
       | ABC\nDEF |
       +----------+

- - ### Nested Class Summary

    - ### 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
    Constructor and Description
    `DelimiterBasedFrameDecoder(int maxFrameLength, boolean stripDelimiter, boolean failFast, ChannelBuffer... delimiters)` Creates a new instance.
    `DelimiterBasedFrameDecoder(int maxFrameLength, boolean stripDelimiter, boolean failFast, ChannelBuffer delimiter)` Creates a new instance.
    `DelimiterBasedFrameDecoder(int maxFrameLength, boolean stripDelimiter, ChannelBuffer... delimiters)` Creates a new instance.
    `DelimiterBasedFrameDecoder(int maxFrameLength, boolean stripDelimiter, ChannelBuffer delimiter)` Creates a new instance.
    `DelimiterBasedFrameDecoder(int maxFrameLength, ChannelBuffer... delimiters)` Creates a new instance.
    `DelimiterBasedFrameDecoder(int maxFrameLength, ChannelBuffer delimiter)` Creates a new instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer)` Decodes the received packets so far into a frame.

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

      `actualReadableBytes, afterAdd, afterRemove, appendToCumulation, beforeAdd, beforeRemove, channelClosed, channelDisconnected, cleanup, decodeLast, exceptionCaught, getMaxCumulationBufferCapacity, getMaxCumulationBufferComponents, internalBuffer, isUnfold, messageReceived, 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

    - #### DelimiterBasedFrameDecoder

          public DelimiterBasedFrameDecoder(int maxFrameLength,
                                    ChannelBuffer delimiter)

      Creates a new instance.
      Parameters:
        `maxFrameLength` - the maximum length of the decoded frame. A `TooLongFrameException` is thrown if the length of the frame exceeds this value.
        `delimiter` - the delimiter

    - #### DelimiterBasedFrameDecoder

          public DelimiterBasedFrameDecoder(int maxFrameLength,
                                    boolean stripDelimiter,
                                    ChannelBuffer delimiter)

      Creates a new instance.
      Parameters:
        `maxFrameLength` - the maximum length of the decoded frame. A `TooLongFrameException` is thrown if the length of the frame exceeds this value.
        `stripDelimiter` - whether the decoded frame should strip out the delimiter or not
        `delimiter` - the delimiter

    - #### DelimiterBasedFrameDecoder

          public DelimiterBasedFrameDecoder(int maxFrameLength,
                                    boolean stripDelimiter,
                                    boolean failFast,
                                    ChannelBuffer delimiter)

      Creates a new instance.
      Parameters:
        `maxFrameLength` - the maximum length of the decoded frame. A `TooLongFrameException` is thrown if the length of the frame exceeds this value.
        `stripDelimiter` - whether the decoded frame should strip out the delimiter or not
        `failFast` - If `true`, a `TooLongFrameException` is thrown as soon as the decoder notices the length of the frame will exceed `maxFrameLength` regardless of whether the entire frame has been read. If `false`, a `TooLongFrameException` is thrown after the entire frame that exceeds `maxFrameLength` has been read.
        `delimiter` - the delimiter

    - #### DelimiterBasedFrameDecoder

          public DelimiterBasedFrameDecoder(int maxFrameLength,
                                    ChannelBuffer... delimiters)

      Creates a new instance.
      Parameters:
        `maxFrameLength` - the maximum length of the decoded frame. A `TooLongFrameException` is thrown if the length of the frame exceeds this value.
        `delimiters` - the delimiters

    - #### DelimiterBasedFrameDecoder

          public DelimiterBasedFrameDecoder(int maxFrameLength,
                                    boolean stripDelimiter,
                                    ChannelBuffer... delimiters)

      Creates a new instance.
      Parameters:
        `maxFrameLength` - the maximum length of the decoded frame. A `TooLongFrameException` is thrown if the length of the frame exceeds this value.
        `stripDelimiter` - whether the decoded frame should strip out the delimiter or not
        `delimiters` - the delimiters

    - #### DelimiterBasedFrameDecoder

          public DelimiterBasedFrameDecoder(int maxFrameLength,
                                    boolean stripDelimiter,
                                    boolean failFast,
                                    ChannelBuffer... delimiters)

      Creates a new instance.
      Parameters:
        `maxFrameLength` - the maximum length of the decoded frame. A `TooLongFrameException` is thrown if the length of the frame exceeds this value.
        `stripDelimiter` - whether the decoded frame should strip out the delimiter or not
        `failFast` - If `true`, a `TooLongFrameException` is thrown as soon as the decoder notices the length of the frame will exceed `maxFrameLength` regardless of whether the entire frame has been read. If `false`, a `TooLongFrameException` is thrown after the entire frame that exceeds `maxFrameLength` has been read.
        `delimiters` - the delimiters

  - ### Method Detail

    - #### decode

          protected Object decode(ChannelHandlerContext ctx,
                      Channel channel,
                      ChannelBuffer buffer)
                           throws Exception

      Description copied from class: `FrameDecoder`
      Decodes the received packets so far into a frame.
      Specified by:
        `decode` in class `FrameDecoder`
      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.
      Returns:
        the decoded frame if a full frame was received and decoded. `null` if there's not enough data in the buffer to decode a frame.
      Throws:
        `Exception`

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