org.apache.mina.filter.codec.demux

## Class DemuxingProtocolDecoder

- java.lang.Object
- - org.apache.mina.filter.codec.ProtocolDecoderAdapter
  - - org.apache.mina.filter.codec.CumulativeProtocolDecoder
    - - org.apache.mina.filter.codec.demux.DemuxingProtocolDecoder

- All Implemented Interfaces:
    ProtocolDecoder

      public class DemuxingProtocolDecoder
      extends CumulativeProtocolDecoder

  A composite `ProtocolDecoder` that demultiplexes incoming `IoBuffer` decoding requests into an appropriate `MessageDecoder`.

  ## Internal mechanism of `MessageDecoder` selection

  1. `DemuxingProtocolDecoder` iterates the list of candidate `MessageDecoder`s and calls `MessageDecoder.decodable(IoSession, IoBuffer)`. Initially, all registered `MessageDecoder`s are candidates.
  2. If `MessageDecoderResult.NOT_OK` is returned, it is removed from the candidate list.
  3. If `MessageDecoderResult.NEED_DATA` is returned, it is retained in the candidate list, and its `MessageDecoder.decodable(IoSession, IoBuffer)` will be invoked again when more data is received.
  4. If `MessageDecoderResult.OK` is returned, `DemuxingProtocolDecoder` found the right `MessageDecoder`.
  5. If there's no candidate left, an exception is raised. Otherwise, `DemuxingProtocolDecoder` will keep iterating the candidate list.
  Please note that any change of position and limit of the specified `IoBuffer` in `MessageDecoder.decodable(IoSession, IoBuffer)` will be reverted back to its original value.

  Once a `MessageDecoder` is selected, `DemuxingProtocolDecoder` calls `MessageDecoder.decode(IoSession, IoBuffer, ProtocolDecoderOutput)` continuously reading its return value:

  - `MessageDecoderResult.NOT_OK` - protocol violation; `ProtocolDecoderException` is raised automatically.
  - `MessageDecoderResult.NEED_DATA` - needs more data to read the whole message; `MessageDecoder.decode(IoSession, IoBuffer, ProtocolDecoderOutput)` will be invoked again when more data is received.
  - `MessageDecoderResult.OK` - successfully decoded a message; the candidate list will be reset and the selection process will start over.
  Author:
    Apache MINA Project
  See Also:
    `MessageDecoderFactory`, `MessageDecoder`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DemuxingProtocolDecoder()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMessageDecoder(Class<? extends MessageDecoder> decoderClass)`
    `void` | `addMessageDecoder(MessageDecoder decoder)`
    `void` | `addMessageDecoder(MessageDecoderFactory factory)`
    `void` | `dispose(IoSession session)` Releases the cumulative buffer used by the specified `session`.
    `protected boolean` | `doDecode(IoSession session, IoBuffer in, ProtocolDecoderOutput out)` Implement this method to consume the specified cumulative buffer and decode its content into message(s).
    `void` | `finishDecode(IoSession session, ProtocolDecoderOutput out)` Override this method to deal with the closed connection.

    - ### Methods inherited from class org.apache.mina.filter.codec.CumulativeProtocolDecoder

      `decode`

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

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

- - ### Constructor Detail

    - #### DemuxingProtocolDecoder

          public DemuxingProtocolDecoder()

  - ### Method Detail

    - #### addMessageDecoder

          public void addMessageDecoder(Class<? extends MessageDecoder> decoderClass)

    - #### addMessageDecoder

          public void addMessageDecoder(MessageDecoder decoder)

    - #### addMessageDecoder

          public void addMessageDecoder(MessageDecoderFactory factory)

    - #### doDecode

          protected boolean doDecode(IoSession session,
                         IoBuffer in,
                         ProtocolDecoderOutput out)
                              throws Exception

      Implement this method to consume the specified cumulative buffer and decode its content into message(s).
      Specified by:
        `doDecode` in class `CumulativeProtocolDecoder`
        `in` - the cumulative buffer
      Returns:
        `true` if and only if there's more to decode in the buffer and you want to have `doDecode` method invoked again. Return `false` if remaining data is not enough to decode, then this method will be invoked again when more data is cumulated.
      Throws:
        `Exception` - if cannot decode `in`.

    - #### finishDecode

          public void finishDecode(IoSession session,
                          ProtocolDecoderOutput out)
                            throws Exception

      Override this method to deal with the closed connection. The default implementation does nothing.
      Specified by:
        `finishDecode` in interface `ProtocolDecoder`
      Overrides:
        `finishDecode` in class `ProtocolDecoderAdapter`
      Throws:
        `Exception` - if the read data violated protocol specification

    - #### dispose

          public void dispose(IoSession session)
                       throws Exception

      Releases the cumulative buffer used by the specified `session`. Please don't forget to call `super.dispose( session )` when you override this method.
      Specified by:
        `dispose` in interface `ProtocolDecoder`
      Overrides:
        `dispose` in class `CumulativeProtocolDecoder`
      Throws:
        `Exception` - if failed to dispose all resources

Copyright © 2004-2012 Apache MINA Project. All Rights Reserved.