Netty in Action — Chapter 6

ChannelHandler

The Channel lifecycle

接口Channel定义了一些简单但是有用的状态模型

状态	描述
ChannelUnregistered	Channel已经创建，但是还没有注册到EventLoop上
ChannelRegistered	Channel已经注册到EventLoop
ChannelActive	Channel已经激活了（已经连接到远程端），现在它已经准备好接受和发送信息
ChannelInactive	Channel没有连接到远程端

The ChannelHandler lifecycle

接口ChannelHandler定义了操作的生命周期，这些操作将会在ChannelHandler加入或者移除ChannelPipeline的时候被调用，每一个方法接收一个ChannelHandlerContext的入参

类型	描述
handlerAdded	当一个ChannelHandler被载入ChannelPipeline的时候触发
handlerRemoved	当一个ChannelHandler从ChannelPipeline中移除的时候触发
exceptionCaught	在处理过程中ChannelPipeline发生了异常

Netty定义了ChannelHandler两个比较重要的子接口

• ChannelInboundHandler------处理输入数据和所有的状态改变
• ChannelOutboundHandler--------处理输出数据，运行拦截一切的操作

Interface ChannelInboundHandler

类型	描述
channelRegistered	Invoked when a Channel is registered to its EventLoop and is able to handle I/O.
channelUnregistered	Invoked when a Channel is deregistered from its EventLoop and can’t handle any I/O.
channelActive	Invoked when a Channel is active; the Channel is connected/ bound and ready.
...	...

当ChannelInboundHandler的实现重写了channelRead()，就要负责通过ReferenceCountUtil.release()显示的释放ByteBuf实例占用的内存
可以选择继承SimpleChannelInboundHandler类，该类会自动释放内存，因此注意不要将后续要用到的引用存入message中

Interface ChannelOutboundHandler

ChannelOutboundHandler的方法可以被Channel, ChannelPipeline和ChannelHandlerContext调用；ChannelOutboundHandler的一个强大的功能是可以根据请求延迟一个操作或一个事件，这使得它可以以复杂的逻辑来处理请求。
ChannelOutboundHandler的很多方法用ChannelPromise作为参数来通知操作的完成，ChannelPromise作为ChannelFuture的子类来定义了一些写的方法，例如setSuccess和setFailure方法，这样可以使ChannelFuture看起来immutable

ChannelHandler adapters

ChannelHandlerAdapter class hierarchy
ChannelHandlerAdapter还提供一个特殊的方法isSharable的方法，如果该接口的具体实现以“Sharable”注解的话，那么将会返回true，这就表示这个实现可以被加入到多个不同的ChannelPipeline中去

Resource management

当你通过调用ChannelInboundHandler.channelRead()或者ChannelOutboundHandler.write()这些方法来操作数据的时候，你都需要保证没有资源泄漏。
为了帮助你诊断这些潜在的问题，Netty提供了一个叫做ResourceLeakDetector的类，这个类将会对你的引用中1%的buffer分配进行取样来分析你的内存泄漏。

等级	描述
DISABLED	禁止使用内存检测，只有经过全面的测试才能使用
SIMPLE	使用默认的1%的测试样例来记录任何的使用泄漏的情况，使用这种默认的级别对于大多数的案例来说是一个不错的选择
ADVANCED	报告发现泄漏的情况且找出该信息所在的位置，依旧使用默认的测试样例比例
PARANOID	与ADVANCED一样，除了它将所有的buffer作为测试样例，这对性能有很大的负担，这应该用在测试debug阶段

泄漏检查等级可以在下面的java系统的变量中设置：

java -Dio.netty.leakDetectionLevel=ADVANCED

Interface ChannelPipeline

可以将ChannelPipeline想象为由多个ChannelHandler链接而成的一种结构，由ChannelHandlerContext负责ChannelHandler和它所属的ChannelPipeline的进行交互。

Modifying a ChannelPipeline

一个ChannelHandler可以实时的通过移除，增加或者替换其他的ChannelHandler来修改一个ChannelPipeline的布局，通过以下方法：

• addFirst()
• addBefore()
• addAfter()
• addLast()
• replace()

正常情况下，每一个在ChannelPipeline中的ChannelHandler都是通过它的EventLoop线程来处理通过它的事件的，这是非常重要的，因为它不会阻塞当前线程

Interface ChannelHandlerContext

一个ChannelHandlerContext代表了一个ChannelHandler和ChannelPipeline之间的关系，ChannelHandlerContext创建于ChannelHandler被载入到ChannelPipeline的时候，ChannelHandlerContext主要功能是管理在同一ChannelPipeline中各个ChannelHandler的交互

ChannelHandlerContext有很多方法，其中的一些方法也出现在Channel和ChannelPipeline中，但是相同的方法却有一些不同的效果，如果你在Channel或者在ChannelPipeline实例中实现这些方法，它们会传播到整个管道，同样的方法如果被ChannelHandlerContext执行的时候，那么它会在当前关联的ChannelHandler中开始执行，然后只会传播到管道中符合条件（符合方向的有兴趣的）的下一个ChannelHandler处理
当使用ChannelHandlerContext时，应该注意：

1. 与ChannelHandler关联的ChannelHandlerContext不会发生改变，因此缓存其引用时安全的
2. 相比于其他类，ChannelHandlerContext的方法包含更短的事件流，可以提供更好的性能

Using ChannelHandlerContext

Channel, ChannelPipeline, ChannelHandler, ChannelHandlerContext的关系
我们可以从ChannelHandlerContext对象中获取Channel和ChannelPipe，然后通过他们的write()方法在pipe中产生一个输入流，这个输入流贯穿整个pipe
如果项从某一个ChannelHandler处开始一个事件流，可以使用前一个ChannelHandler的ChannelHandlerContext的write()方法：

ChannelHandlerContext ctx = ..;
// write() sends the buffer to the next ChannelHandler
ctx.write(Unpooled.copiedBuffer("Netty in Action", CharsetUtil.UTF_8));

Advanced uses of ChannelHandler and ChannelHandlerContext

• ChannelHandlerContext对象可以返回绑定的ChannelPipe对象，这意味着我们可以动态的添加一些ChannelHandler到这个ChannelPipe对象中，从而支持动态的协议更改
• 通过缓存ChannelHandlerContext对象的引用，可以稍后在ChannelHandler方法外，甚至不同线程中使用
• ChannelHandler如果需要被多个ChannelPipe共享，必须加上@Sharable的注释，且是无状态的，保证线程安全

Exception handling

Handling inbound exceptions

在输入事件处理过程中一个异常抛出时，这个异常将会在触发该异常的ChannelInboundHandler的地方开始在ChannelPipeline传播，为了处理这样的异常，你需要在你的ChannelPipeline实现中重写如下的方法：

public class InboundExceptionHandler extends ChannelInboundHandlerAdapter {
    @Override
    public void exceptionCaught(ChannelHandlerContext ctx,
    Throwable cause) {
        cause.printStackTrace();
        ctx.close();
    }
}

注意：

• 默认的ChannelHandler的exceptionCaught的实现会把异常传给管道中的下一个处理器
• 如果一个异常到达了一个管道的结尾，它将被记录为未被处理
• 来定义自定义的处理，你重写了exceptionCaught方法，这将是你自己的决定你是否决定将其接着传播到下游处理器

Handling outbound exceptions

在输入事件的处理中，需要根据返回的ChannelFuture来判断是正常完成任务还是抛出异常；ChannelOutboundHandler也会传递一个ChannelPromise实例，作为ChannelFuture的子类，它也可以被监听器管控来获取异步通知，但是ChannelPromise为实时通知提供可写的方法：

ChannelPromise setSuccess();
ChannelPromise setFailure(Throwable cause);

通过在ChannelFuture或ChannelPromise添加ChannelFutureListener监听器来自定义处理异常；
如果ChannelOutboundHandler本身抛出异常，将会通知其相关联的ChannelPromise来处理