org.apache.mina.filter.codec

## Class CumulativeProtocolDecoder

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

- All Implemented Interfaces:
    ProtocolDecoder
  Direct Known Subclasses:
    DemuxingProtocolDecoder, ImageRequestDecoder, ImageResponseDecoder, ObjectSerializationDecoder, PrefixedStringDecoder

      public abstract class CumulativeProtocolDecoder
      extends ProtocolDecoderAdapter

  A `ProtocolDecoder` that cumulates the content of received buffers to a cumulative buffer to help users implement decoders.

  If the received `IoBuffer` is only a part of a message. decoders should cumulate received buffers to make a message complete or to postpone decoding until more buffers arrive.

  Here is an example decoder that decodes CRLF terminated lines into `Command` objects:

       public class CrLfTerminatedCommandLineDecoder
               extends CumulativeProtocolDecoder {

           private Command parseCommand(IoBuffer in) {
               // Convert the bytes in the specified buffer to a
               // Command object.
               ...
           }

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

               // Remember the initial position.
               int start = in.position();

               // Now find the first CRLF in the buffer.
               byte previous = 0;
               while (in.hasRemaining()) {
                   byte current = in.get();

                   if (previous == '\r' && current == '\n') {
                       // Remember the current position and limit.
                       int position = in.position();
                       int limit = in.limit();
                       try {
                           in.position(start);
                           in.limit(position);
                           // The bytes between in.position() and in.limit()
                           // now contain a full CRLF terminated line.
                           out.write(parseCommand(in.slice()));
                       } finally {
                           // Set the position to point right after the
                           // detected line and set the limit to the old
                           // one.
                           in.position(position);
                           in.limit(limit);
                       }
                       // Decoded one line; CumulativeProtocolDecoder will
                       // call me again until I return false. So just
                       // return true until there are no more lines in the
                       // buffer.
                       return true;
                   }

                   previous = current;
               }

               // Could not find CRLF in the buffer. Reset the initial
               // position to the one we recorded above.
               in.position(start);

               return false;
           }
       }

  Please note that this decoder simply forward the call to `doDecode(IoSession, IoBuffer, ProtocolDecoderOutput)` if the underlying transport doesn't have a packet fragmentation. Whether the transport has fragmentation or not is determined by querying `TransportMetadata`.

  Author:
    Apache MINA Project

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CumulativeProtocolDecoder()` Creates a new instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `decode(IoSession session, IoBuffer in, ProtocolDecoderOutput out)` Cumulates content of `in` into internal buffer and forwards decoding request to `doDecode(IoSession, IoBuffer, ProtocolDecoderOutput)`.
    `void` | `dispose(IoSession session)` Releases the cumulative buffer used by the specified `session`.
    `protected abstract boolean` | `doDecode(IoSession session, IoBuffer in, ProtocolDecoderOutput out)` Implement this method to consume the specified cumulative buffer and decode its content into message(s).

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

      `finishDecode`

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

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

- - ### Constructor Detail

    - #### CumulativeProtocolDecoder

          protected CumulativeProtocolDecoder()

      Creates a new instance.

  - ### Method Detail

    - #### decode

          public void decode(IoSession session,
                    IoBuffer in,
                    ProtocolDecoderOutput out)
                      throws Exception

      Cumulates content of `in` into internal buffer and forwards decoding request to `doDecode(IoSession, IoBuffer, ProtocolDecoderOutput)`. `doDecode()` is invoked repeatedly until it returns `false` and the cumulative buffer is compacted after decoding ends.
      Throws:
        `IllegalStateException` - if your `doDecode()` returned `true` not consuming the cumulative buffer.
        `Exception` - if the read data violated protocol specification

    - #### doDecode

          protected abstract 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).
      Parameters:
        `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`.

    - #### 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 `ProtocolDecoderAdapter`
      Throws:
        `Exception` - if failed to dispose all resources

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