Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  ObjectSerializationDecoder

    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 `ByteBuffer` 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(ByteBuffer in) {
             // Convert the bytes in the specified buffer to a
             // Command object.
             ...
         }

         protected boolean doDecode(IoSession session, ByteBuffer 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;
         }
     }

Version:
  $Rev: 555855 $, $Date: 2007-07-13 05:19:00 +0200 (Fri, 13 Jul 2007) $
Author:
  The Apache Directory Project (mina-dev@directory.apache.org)

Constructor Summary
`protected` | `CumulativeProtocolDecoder()` Creates a new instance.

Method Summary
`void` | `decode(IoSession session, ByteBuffer in, ProtocolDecoderOutput out)` Cumulates content of `in` into internal buffer and forwards decoding request to `doDecode(IoSession, ByteBuffer, ProtocolDecoderOutput)`.
`void` | `dispose(IoSession session)` Releases the cumulative buffer used by the specified `session`.
`protected abstract boolean` | `doDecode(IoSession session, ByteBuffer 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,
                       ByteBuffer in,
                       ProtocolDecoderOutput out)
                throws Exception

  Cumulates content of `in` into internal buffer and forwards decoding request to `doDecode(IoSession, ByteBuffer, 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,
                                        ByteBuffer 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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