Class FrameDecoder
- java.lang.Object
-
- org.jboss.netty.channel.SimpleChannelUpstreamHandler
-
- org.jboss.netty.handler.codec.frame.FrameDecoder
-
- All Implemented Interfaces:
ChannelHandler
,ChannelUpstreamHandler
,LifeCycleAwareChannelHandler
- Direct Known Subclasses:
BigIntegerDecoder
,DelimiterBasedFrameDecoder
,FixedLengthFrameDecoder
,LengthFieldBasedFrameDecoder
,LineBasedFrameDecoder
,PortUnificationServerHandler
,ProtobufVarint32FrameDecoder
,ReplayingDecoder
,SpdyFrameCodec
,SslHandler
public abstract class FrameDecoder extends SimpleChannelUpstreamHandler implements LifeCycleAwareChannelHandler
Decodes the receivedChannelBuffer
s into a meaningful frame object.In a stream-based transport such as TCP/IP, packets can be fragmented and reassembled during transmission even in a LAN environment. For example, let us assume you have received three packets:
+-----+-----+-----+ | ABC | DEF | GHI | +-----+-----+-----+
because of the packet fragmentation, a server can receive them like the following:+----+-------+---+---+ | AB | CDEFG | H | I | +----+-------+---+---+
FrameDecoder
helps you defrag the received packets into one or more meaningful frames that could be easily understood by the application logic. In case of the example above, yourFrameDecoder
implementation could defrag the received packets like the following:+-----+-----+-----+ | ABC | DEF | GHI | +-----+-----+-----+
The following code shows an example handler which decodes a frame whose first 4 bytes header represents the length of the frame, excluding the header.
MESSAGE FORMAT ============== Offset: 0 4 (Length + 4) +--------+------------------------+ Fields: | Length | Actual message content | +--------+------------------------+ DECODER IMPLEMENTATION ====================== public class IntegerHeaderFrameDecoder extends
FrameDecoder
{@Override
protected Object decode(ChannelHandlerContext
ctx,channel
,ChannelBuffer
buf) throws Exception { // Make sure if the length field was received. if (buf.readableBytes() < 4) { // The length field was not received yet - return null. // This method will be invoked again when more packets are // received and appended to the buffer. return null; } // The length field is in the buffer. // Mark the current buffer position before reading the length field // because the whole frame might not be in the buffer yet. // We will reset the buffer position to the marked position if // there's not enough bytes in the buffer. buf.markReaderIndex(); // Read the length field. int length = buf.readInt(); // Make sure if there's enough bytes in the buffer. if (buf.readableBytes() < length) { // The whole bytes were not received yet - return null. // This method will be invoked again when more packets are // received and appended to the buffer. // Reset to the marked position to read the length field again // next time. buf.resetReaderIndex(); return null; } // There's enough bytes in the buffer. Read it.ChannelBuffer
frame = buf.readBytes(length); // Successfully decoded a frame. Return the decoded frame. return frame; } }Returning a POJO rather than a
ChannelBuffer
Please note that you can return an object of a different type than
ChannelBuffer
in yourdecode()
anddecodeLast()
implementation. For example, you could return a POJO so that the nextChannelUpstreamHandler
receives aMessageEvent
which contains a POJO rather than aChannelBuffer
.Replacing a decoder with another decoder in a pipeline
If you are going to write a protocol multiplexer, you will probably want to replace a
FrameDecoder
(protocol detector) with anotherFrameDecoder
orReplayingDecoder
(actual protocol decoder). It is not possible to achieve this simply by callingChannelPipeline.replace(ChannelHandler, String, ChannelHandler)
, but some additional steps are required:public class FirstDecoder extends
FrameDecoder
{ public FirstDecoder() { super(true); // Enable unfold }@Override
protected Object decode(ChannelHandlerContext
ctx,Channel
channel,ChannelBuffer
buf) { ... // Decode the first message Object firstMessage = ...; // Add the second decoder ctx.getPipeline().addLast("second", new SecondDecoder()); // Remove the first decoder (me) ctx.getPipeline().remove(this); if (buf.readable()) { // Hand off the remaining data to the second decoder return new Object[] { firstMessage, buf.readBytes(buf.readableBytes()) }; } else { // Nothing to hand off return firstMessage; } } }
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler
ChannelHandler.Sharable
-
-
Field Summary
Fields Modifier and Type Field Description protected ChannelBuffer
cumulation
static int
DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
-
Constructor Summary
Constructors Modifier Constructor Description protected
FrameDecoder()
protected
FrameDecoder(boolean unfold)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected int
actualReadableBytes()
Returns the actual number of readable bytes in the internal cumulative buffer of this decoder.void
afterAdd(ChannelHandlerContext ctx)
void
afterRemove(ChannelHandlerContext ctx)
protected ChannelBuffer
appendToCumulation(ChannelBuffer input)
void
beforeAdd(ChannelHandlerContext ctx)
void
beforeRemove(ChannelHandlerContext ctx)
void
channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e)
Invoked when aChannel
was closed and all its related resources were released.void
channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e)
Invoked when aChannel
was disconnected from its remote peer.protected void
cleanup(ChannelHandlerContext ctx, ChannelStateEvent e)
protected abstract Object
decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer)
Decodes the received packets so far into a frame.protected Object
decodeLast(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer)
Decodes the received data so far into a frame when the channel is disconnected.void
exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e)
Invoked when an exception was raised by an I/O thread or aChannelHandler
.protected ChannelBuffer
extractFrame(ChannelBuffer buffer, int index, int length)
Extract a Frame of the specified buffer.int
getMaxCumulationBufferCapacity()
SeesetMaxCumulationBufferCapacity(int)
for explaintation of this settingint
getMaxCumulationBufferComponents()
Returns the maximum number of components in the cumulation buffer.protected ChannelBuffer
internalBuffer()
Returns the internal cumulative buffer of this decoder.boolean
isUnfold()
void
messageReceived(ChannelHandlerContext ctx, MessageEvent e)
Invoked when a message object (e.g:ChannelBuffer
) was received from a remote peer.protected ChannelBuffer
newCumulationBuffer(ChannelHandlerContext ctx, int minimumCapacity)
Create a newChannelBuffer
which is used for the cumulation.void
replace(String handlerName, ChannelHandler handler)
void
setMaxCumulationBufferCapacity(int copyThreshold)
Set the maximal capacity of the internal cumulation ChannelBuffer to use before theFrameDecoder
tries to minimize the memory usage by "byte copy".void
setMaxCumulationBufferComponents(int maxCumulationBufferComponents)
Sets the maximum number of components in the cumulation buffer.void
setUnfold(boolean unfold)
protected void
unfoldAndFireMessageReceived(ChannelHandlerContext context, SocketAddress remoteAddress, Object result)
protected ChannelBuffer
updateCumulation(ChannelHandlerContext ctx, ChannelBuffer input)
-
Methods inherited from class org.jboss.netty.channel.SimpleChannelUpstreamHandler
channelBound, channelConnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete
-
-
-
-
Field Detail
-
DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
public static final int DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
- See Also:
- Constant Field Values
-
cumulation
protected ChannelBuffer cumulation
-
-
Method Detail
-
isUnfold
public final boolean isUnfold()
-
setUnfold
public final void setUnfold(boolean unfold)
-
getMaxCumulationBufferCapacity
public final int getMaxCumulationBufferCapacity()
SeesetMaxCumulationBufferCapacity(int)
for explaintation of this setting
-
setMaxCumulationBufferCapacity
public final void setMaxCumulationBufferCapacity(int copyThreshold)
Set the maximal capacity of the internal cumulation ChannelBuffer to use before theFrameDecoder
tries to minimize the memory usage by "byte copy". What you use here really depends on your application and need. UsingInteger.MAX_VALUE
will disable all byte copies but give you the cost of a higher memory usage if bigChannelBuffer
's will be received. By default a threshold of0
is used, which means it will always copy to try to reduce memory usage- Parameters:
copyThreshold
- the threshold (in bytes) orInteger.MAX_VALUE
to disable it. The value must be at least 0- Throws:
IllegalStateException
- get thrown if someone tries to change this setting after the Decoder was added to theChannelPipeline
-
getMaxCumulationBufferComponents
public final int getMaxCumulationBufferComponents()
Returns the maximum number of components in the cumulation buffer. If the number of the components in the cumulation buffer exceeds this value, the components of the cumulation buffer are consolidated into a single component, involving memory copies. The default value of this propertyDEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
.
-
setMaxCumulationBufferComponents
public final void setMaxCumulationBufferComponents(int maxCumulationBufferComponents)
Sets the maximum number of components in the cumulation buffer. If the number of the components in the cumulation buffer exceeds this value, the components of the cumulation buffer are consolidated into a single component, involving memory copies. The default value of this property isDEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
and its minimum allowed value is2
.
-
messageReceived
public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) throws Exception
Description copied from class:SimpleChannelUpstreamHandler
Invoked when a message object (e.g:ChannelBuffer
) was received from a remote peer.- Overrides:
messageReceived
in classSimpleChannelUpstreamHandler
- Throws:
Exception
-
appendToCumulation
protected ChannelBuffer appendToCumulation(ChannelBuffer input)
-
updateCumulation
protected ChannelBuffer updateCumulation(ChannelHandlerContext ctx, ChannelBuffer input)
-
channelDisconnected
public void channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
Description copied from class:SimpleChannelUpstreamHandler
Invoked when aChannel
was disconnected from its remote peer.- Overrides:
channelDisconnected
in classSimpleChannelUpstreamHandler
- Throws:
Exception
-
channelClosed
public void channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
Description copied from class:SimpleChannelUpstreamHandler
Invoked when aChannel
was closed and all its related resources were released.- Overrides:
channelClosed
in classSimpleChannelUpstreamHandler
- Throws:
Exception
-
exceptionCaught
public void exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) throws Exception
Description copied from class:SimpleChannelUpstreamHandler
Invoked when an exception was raised by an I/O thread or aChannelHandler
.- Overrides:
exceptionCaught
in classSimpleChannelUpstreamHandler
- Throws:
Exception
-
decode
protected abstract Object decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer) throws Exception
Decodes the received packets so far into a frame. If an sub-class wants to extract a frame out of the buffer it should use theextractFrame(ChannelBuffer, int, int)
method, to make optimizations easier later.- Parameters:
ctx
- the context of this handlerchannel
- the current channelbuffer
- the cumulative buffer of received packets so far. Note that the buffer might be empty, which means you should not make an assumption that the buffer contains at least one byte in your decoder implementation.- Returns:
- the decoded frame if a full frame was received and decoded.
null
if there's not enough data in the buffer to decode a frame. - Throws:
Exception
-
decodeLast
protected Object decodeLast(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer) throws Exception
Decodes the received data so far into a frame when the channel is disconnected.- Parameters:
ctx
- the context of this handlerchannel
- the current channelbuffer
- the cumulative buffer of received packets so far. Note that the buffer might be empty, which means you should not make an assumption that the buffer contains at least one byte in your decoder implementation.- Returns:
- the decoded frame if a full frame was received and decoded.
null
if there's not enough data in the buffer to decode a frame. - Throws:
Exception
-
unfoldAndFireMessageReceived
protected final void unfoldAndFireMessageReceived(ChannelHandlerContext context, SocketAddress remoteAddress, Object result)
-
cleanup
protected void cleanup(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
Gets called onchannelDisconnected(ChannelHandlerContext, ChannelStateEvent)
andchannelClosed(ChannelHandlerContext, ChannelStateEvent)
- Throws:
Exception
-
newCumulationBuffer
protected ChannelBuffer newCumulationBuffer(ChannelHandlerContext ctx, int minimumCapacity)
Create a newChannelBuffer
which is used for the cumulation. Sub-classes may override this.- Parameters:
ctx
-ChannelHandlerContext
for this handler- Returns:
- buffer the
ChannelBuffer
which is used for cumulation
-
replace
public void replace(String handlerName, ChannelHandler handler)
Replace thisFrameDecoder
in theChannelPipeline
with the givenChannelHandler
. All remaining bytes in theChannelBuffer
will get send to the newChannelHandler
that was used as replacement
-
actualReadableBytes
protected int actualReadableBytes()
Returns the actual number of readable bytes in the internal cumulative buffer of this decoder. You usually do not need to rely on this value to write a decoder. Use it only when you muse use it at your own risk. This method is a shortcut tointernalBuffer().readableBytes()
.
-
internalBuffer
protected ChannelBuffer internalBuffer()
Returns the internal cumulative buffer of this decoder. You usually do not need to access the internal buffer directly to write a decoder. Use it only when you must use it at your own risk.
-
extractFrame
protected ChannelBuffer extractFrame(ChannelBuffer buffer, int index, int length)
Extract a Frame of the specified buffer. By default this implementation will return a extract the sub-region of the buffer and create a new one. If an sub-class want to extract a frame from the buffer it should use this method by default. Be sure that this method MUST not modify the readerIndex of the given buffer
-
beforeAdd
public void beforeAdd(ChannelHandlerContext ctx) throws Exception
- Specified by:
beforeAdd
in interfaceLifeCycleAwareChannelHandler
- Throws:
Exception
-
afterAdd
public void afterAdd(ChannelHandlerContext ctx) throws Exception
- Specified by:
afterAdd
in interfaceLifeCycleAwareChannelHandler
- Throws:
Exception
-
beforeRemove
public void beforeRemove(ChannelHandlerContext ctx) throws Exception
- Specified by:
beforeRemove
in interfaceLifeCycleAwareChannelHandler
- Throws:
Exception
-
afterRemove
public void afterRemove(ChannelHandlerContext ctx) throws Exception
- Specified by:
afterRemove
in interfaceLifeCycleAwareChannelHandler
- Throws:
Exception
-
-