org.apache.mina.filter.codec
Class CumulativeProtocolDecoder

java.lang.Object
  extended by org.apache.mina.filter.codec.ProtocolDecoderAdapter
      extended by 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 a list of integers:

 public class IntegerDecoder extends CumulativeProtocolDecoder {
 
     public IntegerDecoder() {
         super(4);
     }
 
     protected boolean doDecode(IoSession session, ByteBuffer in,
                                ProtocolDecoderOutput out) throws ProtocolViolationException {
         if (in.remaining() < 4) {
             return false; // Cumulate remainder to decode later.
         }
         
         out.write(new Integer(in.getInt()));
 
         // Decoded one integer; CumulativeProtocolDecoder will call me again,
         // so I can decode as many integers as possible.
         return true;
     }
 }
 

Version:
$Rev: 393303 $, $Date: 2006-04-12 05:11:35 +0900 (Wed, 12 Apr 2006) $
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 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