Package 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	Description
DemuxingProtocolDecoder()

Method Summary

Modifier and Type	Method	Description
void	addMessageDecoder(Class<? extends MessageDecoder> decoderClass)	Adds a new message decoder class
void	addMessageDecoder(MessageDecoder decoder)	Adds a new message decoder instance
void	addMessageDecoder(MessageDecoderFactory factory)	Adds a new message decoder 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, setTransportMetadataFragmentation

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)

Adds a new message decoder class

Parameters:

decoderClass - The decoder class

addMessageDecoder

public void addMessageDecoder(MessageDecoder decoder)

Adds a new message decoder instance

Parameters:

decoder - The decoder instance

addMessageDecoder

public void addMessageDecoder(MessageDecoderFactory factory)

Adds a new message decoder factory

Parameters:

factory - The decoder 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

Parameters:

session - The current Session

in - the cumulative buffer

out - The ProtocolDecoderOutput that will receive the decoded message

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

Parameters:

session - The current Session

out - The ProtocolDecoderOutput that contains the decoded message

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

Parameters:

session - The current Session

Throws:

Exception - if failed to dispose all resources