org.jboss.netty.handler.codec.frame
类 FrameDecoder

java.lang.Object
  org.jboss.netty.channel.SimpleChannelUpstreamHandler
      org.jboss.netty.handler.codec.frame.FrameDecoder

所有已实现的接口：

ChannelHandler, ChannelUpstreamHandler

直接已知子类：

DelimiterBasedFrameDecoder, FixedLengthFrameDecoder, LengthFieldBasedFrameDecoder, ProtobufVarint32FrameDecoder, SslHandler

public abstract class FrameDecoder
extends SimpleChannelUpstreamHandler

Decodes the received ChannelBuffers 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, your FrameDecoder 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 your decode() and decodeLast() implementation. For example, you could return a POJO so that the next ChannelUpstreamHandler receives a MessageEvent which contains a POJO rather than a ChannelBuffer.

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 another FrameDecoder or ReplayingDecoder (actual protocol decoder). It is not possible to achieve this simply by calling ChannelPipeline.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;
         }
     }
 }
 

嵌套类摘要

从接口 org.jboss.netty.channel.ChannelHandler 继承的嵌套类/接口

ChannelHandler.Sharable

方法摘要

void	channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e) 当一个Channel被关闭且它所有关联的资源被释放时调用.
void	channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e) 当一个Channel被远程端断开连接时调用.
void	exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) 当一个I/O线程或ChannelHandler抛出异常时被调用.
void	messageReceived(ChannelHandlerContext ctx, MessageEvent e) 当一个从远端发来的消息对象(如: ChannelBuffer)被接收时调用.

从类 org.jboss.netty.channel.SimpleChannelUpstreamHandler 继承的方法

channelBound, channelConnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete

从类 java.lang.Object 继承的方法

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

方法详细信息

messageReceived

public void messageReceived(ChannelHandlerContext ctx,
                            MessageEvent e)
                     throws java.lang.Exception

从类 SimpleChannelUpstreamHandler 复制的描述

当一个从远端发来的消息对象(如: ChannelBuffer)被接收时调用.

覆盖：

类 SimpleChannelUpstreamHandler 中的 messageReceived

抛出：

java.lang.Exception

channelDisconnected

public void channelDisconnected(ChannelHandlerContext ctx,
                                ChannelStateEvent e)
                         throws java.lang.Exception

从类 SimpleChannelUpstreamHandler 复制的描述

当一个Channel被远程端断开连接时调用.

覆盖：

类 SimpleChannelUpstreamHandler 中的 channelDisconnected

抛出：

java.lang.Exception

channelClosed

public void channelClosed(ChannelHandlerContext ctx,
                          ChannelStateEvent e)
                   throws java.lang.Exception

从类 SimpleChannelUpstreamHandler 复制的描述

当一个Channel被关闭且它所有关联的资源被释放时调用.

覆盖：

类 SimpleChannelUpstreamHandler 中的 channelClosed

抛出：

java.lang.Exception

exceptionCaught

public void exceptionCaught(ChannelHandlerContext ctx,
                            ExceptionEvent e)
                     throws java.lang.Exception

从类 SimpleChannelUpstreamHandler 复制的描述

当一个I/O线程或ChannelHandler抛出异常时被调用.

覆盖：

类 SimpleChannelUpstreamHandler 中的 exceptionCaught

抛出：

java.lang.Exception