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.

See Also:

• MessageDecoderFactory
• MessageDecoder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	DemuxingProtocolDecoder.DefaultConstructorMessageDecoderFactory
private static class	DemuxingProtocolDecoder.SingletonMessageDecoderFactory
private class	DemuxingProtocolDecoder.State

Field Summary

Fields

Modifier and Type	Field	Description
private MessageDecoderFactory[]	decoderFactories
private static final Class<?>[]	EMPTY_PARAMS
private static final AttributeKey	STATE

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.
private DemuxingProtocolDecoder.State	getState(IoSession session)

Methods inherited from class CumulativeProtocolDecoder

decode, setTransportMetadataFragmentation

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

STATE

private static final AttributeKey STATE

decoderFactories

private MessageDecoderFactory[] decoderFactories

EMPTY_PARAMS

private static final Class<?>[] EMPTY_PARAMS

Constructor Details

DemuxingProtocolDecoder

public DemuxingProtocolDecoder()

Method Details

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

getState

private DemuxingProtocolDecoder.State getState(IoSession session)
                                        throws Exception

Throws:

Exception