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 MessageDecoders and calls MessageDecoder.decodable(IoSession, IoBuffer). Initially, all registered MessageDecoders 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