ChannelHandler

Channel 有个简单但强大的状态模型，与 ChannelInboundHandler API 密切相关。下面表格是 Channel 的四个状态：

Channel 的正常的生命周期如下图，当这些状态变化出现，对应的事件将会生成，这样与 ChannelPipeline 中的 ChannelHandler 的交互就能及时响应：

ChannelHandler 定义的生命周期操作如下表：

当 ChannelHandler 添加到 ChannelPipeline，或者从 ChannelPipeline 移除后，这些将会调用。每个方法都会带 ChannelHandlerContext 参数

Netty 提供2个重要的 ChannelHandler 子接口：

• ChannelInboundHandler: 处理进站数据，并且所有状态都更改
• ChannelOutboundHandler: 处理出站数据，允许拦截各种操作

当你通过 ChannelInboundHandler.channelRead(…) 或者 ChannelOutboundHandler.write(…) 来处理数据，重要的是 在处理资源时要确保资源不要泄漏

Netty 使用引用计数器来处理池化的 ByteBuf。所以当 ByteBuf 完全处理后，要 确保引用计数器被调整

引用计数的权衡之一是用户时必须小心使用消息。当 JVM 仍在 GC这个消息，以至于可能是之前获得的这个消息不会被放回池中。因此很可能，如果你不小心释放这些消息，很可能会耗尽资源

为了让用户更加简单的找到遗漏的释放，Netty 包含了一个 ResourceLeakDetector ，将会从已分配的缓冲区 1% 作为样品来检查是否存在在应用程序泄漏。因为 1% 的抽样，开销很小

对于检测泄漏，您将看到类似于下面的日志消息：

LEAK: ByteBuf.release() was not called before it’s garbage-collected. Enable advanced leak reporting to find out where the leak occurred. To enable advanced
leak reporting, specify the JVM option ’-Dio.netty.leakDetectionLevel=advanced’ or call ResourceLeakDetector.setLevel()

Relaunch your application with the JVM option mentioned above, then you’ll see the recent locations of your application where the leaked buffer was accessed. The following output shows a leak from our unit test (XmlFrameDecoderTest.testDecodeWithXml()):

Running io.netty.handler.codec.xml.XmlFrameDecoderTest

15:03:36.886 [main] ERROR io.netty.util.ResourceLeakDetector - LEAK:
ByteBuf.release() was not called before it’s garbage-collected.

Recent access records: 1

#1:

io.netty.buffer.AdvancedLeakAwareByteBuf.toString(AdvancedLeakAwareByteBuf.java:697)

io.netty.handler.codec.xml.XmlFrameDecoderTest.testDecodeWithXml(XmlFrameDecoderTest.java:157)
io.netty.handler.codec.xml.XmlFrameDecoderTest.testDecodeWithTwoMessages(XmlFrameDecoderTest.java:133)

ChannelHandler 可以实时修改 ChannelPipeline 的布局，通过添加、移除、替换其他 ChannelHandler（也可以从 ChannelPipeline 移除 ChannelHandler 自身）。这个 是 ChannelHandler 重要的功能之一

ChannelPipeline pipeline = null; // get reference to pipeline
FirstHandler firstHandler = new FirstHandler(); //1 创建一个 FirstHandler 实例
pipeline.addLast("handler1", firstHandler); //2 添加该实例作为 "handler1" 到 ChannelPipeline 
pipeline.addFirst("handler2", new SecondHandler()); //3 添加 SecondHandler 实例作为 "handler2" 到 ChannelPipeline 的第一个槽，这意味着它将替换之前已经存在的 "handler1"
pipeline.addLast("handler3", new ThirdHandler()); //4 添加 ThirdHandler 实例作为"handler3" 到 ChannelPipeline 的最后一个槽

pipeline.remove("handler3"); //5 通过名称移除 "handler3"
pipeline.remove(firstHandler); //6 通过引用移除 FirstHandler (因为只有一个，所以可以不用关联名字 "handler1"）

pipeline.replace("handler2", "handler4", new ForthHandler()); //6 将作为"handler2"的 SecondHandler 实例替换为作为 "handler4"的 FourthHandler

这种轻松添加、移除和替换 ChannelHandler 能力， 适合非常灵活的实现逻辑

   通常每个 ChannelHandler 添加到 ChannelPipeline 将处理事件传递到 EventLoop( I/O 的线程)
   
   至关重要的是不要阻塞这个线程， 它将会负面影响的整体处理I/O
   
   有时可能需要使用阻塞 API 接口来处理遗留代码。对于这个情况下 ChannelPipeline 已有 add() 方法，它接受一个EventExecutorGroup
   
   如果一个定制的 EventExecutorGroup 传入事件将由含在这个 EventExecutorGroup 中的 EventExecutor之一来处理，并且从 Channel 的 EventLoop 本身离开
   
   一个默认实现称为来自 Netty 的 DefaultEventExecutorGroup

除了上述操作，其他访问 ChannelHandler 的方法如下：

ChannelPipeline API 有额外调用入站和出站操作的方法。下表列出了入站操作，用于通知 ChannelPipeline 中 ChannelInboundHandlers 正在发生的事件：

• 一个 ChannelPipeline 是用来保存关联到一个 Channel 的ChannelHandler
• 可以修改 ChannelPipeline 通过动态添加和删除 ChannelHandler
• ChannelPipeline 有着丰富的API调用动作来回应入站和出站事件

下图展示了 ChannelPipeline, Channel, ChannelHandler 和 ChannelHandlerContext 的关系：

1. Channel 绑定到 ChannelPipeline
2. ChannelPipeline 绑定到包含 ChannelHandler 的 Channel
3. ChannelHandler
4. 当添加 ChannelHandler 到 ChannelPipeline 时，ChannelHandlerContext 被创建

下面展示了从 ChannelHandlerContext 获取到 Channel 的引用，通过调用 Channel 上的 write() 方法来触发一个写事件到通过管道的的流中：

ChannelHandlerContext ctx = context;
Channel channel = ctx.channel();  //1 得到与 ChannelHandlerContext 关联的 Channel 的引用
channel.write(Unpooled.copiedBuffer("Netty in Action",
                    CharsetUtil.UTF_8));  //2 通过 Channel 写缓存

下面展示了从 ChannelHandlerContext 获取到 ChannelPipeline 的相同示例：

ChannelHandlerContext ctx = context;
ChannelPipeline pipeline = ctx.pipeline(); //1 得到与 ChannelHandlerContext 关联的 ChannelPipeline 的引用 
pipeline.write(Unpooled.copiedBuffer("Netty in Action",
                     CharsetUtil.UTF_8));  //2 通过 ChannelPipeline 写缓冲区

流在两个清单6.6和6.7是一样的，如图6.4所示。注意： 虽然在 Channel 或者 ChannelPipeline 上调用write() 都会把事件在整个管道传播，但是在 ChannelHandler 级别上，从一个处理程序转到下一个却要通过在 ChannelHandlerContext 调用方法实现 ：

为什么会想从 ChannelPipeline 一个特定的点开始传播一个事件?

• 通过减少 ChannelHandler 不感兴趣的事件的传递，从而减少开销
• 排除掉特定的对此事件感兴趣的处理程序的处理

想要实现从一个特定的 ChannelHandler 开始处理，你必须引用与此 ChannelHandler的前一个ChannelHandler 关联的 ChannelHandlerContext 。这个 ChannelHandlerContext 将会调用与自身关联的 ChannelHandler 的下一个ChannelHandler ：

ChannelHandlerContext ctx = context; // 1 获得 ChannelHandlerContext 的引用
ctx.write(Unpooled.copiedBuffer("Netty in Action",
                CharsetUtil.UTF_8)); // 2 write() 将会把缓冲区发送到下一个 ChannelHandler

如下所示，消息将会从下一个ChannelHandler开始流过 ChannelPipeline ，绕过所有在它之前的ChannelHandler：

1. ChannelHandlerContext 方法调用
2. 事件发送到了下一个 ChannelHandler
3. 经过最后一个ChannelHandler后，事件从 ChannelPipeline 移除

当我们想要调用某个特定的 ChannelHandler操作时，它尤其有用

通过调用 ChannelHandlerContext 的 pipeline() 方法，可以得到一个封闭的 ChannelPipeline 引用。这使得可以在运行时操作 pipeline 的 ChannelHandler ，这一点可以被利用来实现一些复杂的需求，例如,添加一个 ChannelHandler 到 pipeline 来支持动态协议改变

其他高级用例可以实现通过保持一个 ChannelHandlerContext 引用供以后使用，这可能发生在任何 ChannelHandler 方法。甚至来自不同的线程。清单6.9显示了此模式被用来触发一个事件：

public class WriteHandler extends ChannelHandlerAdapter {

    private ChannelHandlerContext ctx;

    @Override
    public void handlerAdded(ChannelHandlerContext ctx) {
        this.ctx = ctx;        //1 存储 ChannelHandlerContext 的引用供以后使用
    }

    public void send(String msg) {
        ctx.writeAndFlush(msg);  //2 使用之前存储的 ChannelHandlerContext 来发送消息
    }
}

因为 ChannelHandler 可以属于多个 ChannelPipeline ，它可以绑定多个 ChannelHandlerContext 实例。然而 ChannelHandler 用于这种用法必须添加 @Sharable 注解。否则试图将它添加到多个 ChannelPipeline 将引发一个异常。此外，它必须既是线程安全的又能安全地使用多个同时的通道(比如,连接)：

@ChannelHandler.Sharable            //1 添加 @Sharable 注解
public class SharableHandler extends ChannelInboundHandlerAdapter {

    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) {
        System.out.println("channel read message " + msg);
        ctx.fireChannelRead(msg);  //2 日志方法调用， 并专递到下一个 ChannelHandler
    }
}

上面这个 ChannelHandler 实现符合所有包含在多个管道的要求，它通过@Sharable 注解，并不持有任何状态。而下面清单6.11中列出的情况则恰恰相反,它会造成问题：

@ChannelHandler.Sharable  //1 添加 @Sharable
public class NotSharableHandler extends ChannelInboundHandlerAdapter {
    private int count;

    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) {
        count++;  //2 count字段递增

        System.out.println("inboundBufferUpdated(...) called the "
                   + count + " time");  //3 日志方法调用， 并专递到下一个 ChannelHandler
        ctx.fireChannelRead(msg);
    }
}

这段代码的问题是它持有状态：一个实例变量保持了方法调用的计数。将这个类的一个实例添加到 ChannelPipeline 并发访问通道时很可能产生错误。(当然，这个简单的例子中可以通过在 channelRead() 上添加 synchronized 来纠正 )

总之 使用@Sharable的话，要确定 ChannelHandler 是线程安全的