org.apache.mina.protocol.codec
Class CumulativeProtocolDecoder

java.lang.Object
  org.apache.mina.protocol.codec.CumulativeProtocolDecoder

All Implemented Interfaces:

ProtocolDecoder

public abstract class CumulativeProtocolDecoder
extends java.lang.Object
implements ProtocolDecoder

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(ProtocolSession 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: 326586 $, $Date: 2005-10-19 17:50:29 +0200 (Wed, 19 Oct 2005) $

Author:

The Apache Directory Project (dev@directory.apache.org)

Constructor Summary

protected

CumulativeProtocolDecoder(int defaultCapacity) Creates a new instance with the specified default capacity of cumulative buffer.

Method Summary

void	decode(ProtocolSession session, ByteBuffer in, ProtocolDecoderOutput out) Cumulates content of in into internal buffer and forwards decoding request to doDecode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput).
protected abstract boolean	doDecode(ProtocolSession 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(int defaultCapacity)

Creates a new instance with the specified default capacity of cumulative buffer. Please note that the capacity increases automatically.

Method Detail

decode

public void decode(ProtocolSession session,
                   ByteBuffer in,
                   ProtocolDecoderOutput out)
            throws ProtocolViolationException

Cumulates content of in into internal buffer and forwards decoding request to doDecode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput). doDecode() is invoked repeatedly until it returns false and the cumulative buffer is compacted after decoding ends.

Specified by:

decode in interface ProtocolDecoder

Throws:

java.lang.IllegalStateException - if your doDecode() returned true not consuming the cumulative buffer.

ProtocolViolationException - if the read data violated protocol specification

doDecode

protected abstract boolean doDecode(ProtocolSession session,
                                    ByteBuffer in,
                                    ProtocolDecoderOutput out)
                             throws ProtocolViolationException

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:

ProtocolViolationException - if cannot decode in.