Read book Netty in action(Chapter VII)--ChannelHandler和ChannelPipeline

序言

我们曾经学过了ByteBuf – netty的数据容器，还有ChannelHandler和ChannelPipeline，这一把将他们组合起来，这些组件的交互正是Netty的灵魂所在！

ChannelHanlder家族

在详细地学习ChannelHanlder之前，我们将在Netty的组件模型的这部门基础上花费一点时间，有可能我会去啃一下源码。

Channel的生命周期

Channel接口提供了一组和ChannelInBoundHandler API相关的但是功能强大的组件模型。Channel有如下4个状态：
1.ChannelUnregistered Channel已经被创建，但是还没有注册到EventLoop上。
2.ChannelRegistered已经成功注册在EventLoop上。
3,.ChannelActive Channel 处于活动状态（已经连接到它的远程节点）。它现在可以接收和发送数据了
4.ChannelInactive Channel 没有连接到远程节点

生命周期是：ChannelRegistered -> ChannelActive -> ChannelInactive -> ChannelUnregistered 当这些状态发生变化时，这些事件会被转化给ChannelPipeline中的ChannelHandler，其可以随后对它们做出
响应。

ChannelHandler 的生命周期

ChannelHandler作为ChannelPipeline的子链，将其添加或者删除都应该可以插入事件，正如监听一个集合，向集合中插入或者删除元素而触发事件一样。这些
方法中的每一个都接受一个ChannelHandlerContext 参数。正如集合在Context环境下，做一些操作一下。当然了，插入错误或者删除的时候出现了线程问题，都应该有一个兜底的事件，而这些事件都应该由调用者决定。

handlerAdded 当把ChannelHandler 添加到ChannelPipeline 中时被调用
handlerRemoved 当从ChannelPipeline 中移除ChannelHandler 时被调用
exceptionCaught 当处理过程中在ChannelPipeline 中有错误产生时被调用

Netty 定义了下面两个重要的ChannelHandler 子接口：
ChannelInboundHandler——处理入站数据以及各种状态变化；
ChannelOutboundHandler——处理出站数据并且允许拦截所有的操作。

ChannelInboundHandler 接口

这些方法将会在数据被接收时或者与其对应的Channel 状态发生改变时被调用。
这些方法与Channel的生命周期密切相关。

channelRegistered 当channel注册到EventLoop上的时候调用。
channelUnregistered 当channel从EvntLoop上注销的时候调用。
channelActive 当channel处于活跃状态的时候调用。
channelInactive 当Channel 离开活动状态并且不再连接它的远程节点时被调用。
channelReadComplete 当Channel上的一个读操作完成时被调用
channelRead 当Channel读取数据时调用
ChannelWritabilityChanged 当Channel 的可写状态发生改变时被调用。用户可以确保写操作不会完成得太快（以避免发生OutOfMemoryError）或者可以在Channel 变为再次可写时恢复写入。可以通过调用Channel 的isWritable()方法来检测Channel 的可写性。与可写性相关的阈值可以通过Channel.config().setWriteHighWaterMark()和Channel.config().setWriteLowWaterMark()方法来设置
userEventTriggered 当ChannelnboundHandler.fireUserEventTriggered()方法被调
用时被调用，因为一个POJO 被传经了ChannelPipeline

当某个ChannelInboundHandler 的实现重写channelRead()方法时，它将负责显式地
释放与池化的ByteBuf 实例相关的内存。Netty 为此提供了一个实用方法ReferenceCountUtil.release()。

public class DiscardHandler extends ChannelInboundHandlerAdapter {
    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
        // discard the msg
        ReferenceCountUtil.release(msg);
    }
}

但是如果你继承了SimpleChannelInboundHandler，并不需要手动释放，因为他会自动的去释放内存。

ChannelOutboundHandler 接口

出站操作和数据将由ChannelOutboundHandler 处理。它的方法将被Channel、ChannelPipeline 以及ChannelHandlerContext 调用。

ChannelOutboundHandler 的一个强大的功能是可以按需推迟操作或者事件，这使得可以通过一些复杂的方法来处理请求。例如，如果到远程节点的写入被暂停了，那么你可以推迟冲刷操作并在稍后继续。

ChannelHandler 适配器

无论是ChannelInboundHandlerAdapter还是ChannelOutboundHandlerAdapter，他们都有一个超类，就是ChannelHandler（通过扩展抽象ChannelHandlerAdapter）。

ChannelHandlerAdapter 还提供了实用方法isSharable()。如果其对应的实现被标注为Sharable，那么这个方法将返回true，表示它可以被添加到多个ChannelPipeline中。

在ChannelInboundHandlerAdapter 和ChannelOutboundHandlerAdapter 中所提供的方法体调用了其相关联的ChannelHandlerContext 上的等效方法，从而将事件转发到了ChannelPipeline 中的下一个ChannelHandler 中。

你要想在自己的ChannelHandler 中使用这些适配器类，只需要简单地扩展它们，并且重写那些你想要自定义的方法。

资源管理

每当通过调用ChannelInboundHandler.channelRead()或者ChannelOutboundHandler.write()方法来处理数据时，你都需要确保没有任何的资源泄漏。
之前曾经说过，我们的ByteBuf是由计数器的，当我们完全的使用了ByteBuf之后，我们是有必要去调整其引用技术的。
为了帮助你诊断潜在的（资源泄漏）问题，Netty提供了ResourceLeakDetector。它将对你应用程序的缓冲区分配做大约1%的采样来检测内存泄露。相关的开销是非常小的。
Netty 目前定义了4 种泄漏检测级别：
DISABLED 禁用泄漏检测。只有在详尽的测试之后才应设置为这个值
SIMPLE 使用1%的默认采样率检测并报告任何发现的泄露。这是默认级别，适合绝大部分的情况
ADVANCED 使用默认的采样率，报告所发现的任何的泄露以及对应的消息被访问的位置
PARANOID 类似于ADVANCED，但是其将会对每次（对消息的）访问都进行采样。这对性能将会有很大的影响，应该只在调试阶段使用。

实现ChannelInboundHandler.channelRead()和ChannelOutboundHandler.write()方法时，应该如何使用这个诊断工具来防止泄露呢？让我们看看你的channelRead()操作直接消费入站消息的情况；也就是说，它不会通过调用ChannelHandlerContext.fireChannelRead()方法将入站消息转发给下一个ChannelInboundHandler

重要的是，不仅要释放资源，还要通知ChannelPromise。否则可能会出现Channel-
FutureListener 收不到某个消息已经被处理了的通知的情况。总之，如果一个消息被消费或者丢弃了，并且没有传递给ChannelPipeline 中的下一个ChannelOutboundHandler，那么用户就有责任调用ReferenceCountUtil.release()。
如果消息到达了实际的传输层，那么当它被写入时或者Channel 关闭时，都将被自动释放。

ChannelPipeline 接口

每一个新创建的Channel 都将会被分配一个新的ChannelPipeline。这项关联是永久性的；Channel 既不能附加另外一个ChannelPipeline，也不能分离其当前的。在Netty 组件的生命周期中，这是一项固定的操作，不需要开发人员的任何干预。很容易理解，同理一个元素绑定到一个链上。根据事件的起源，事件将会被ChannelInboundHandler 或者ChannelOutboundHandler处理，随后，将会到下一站ChannelHandler上处理。。如果一个入站事件被触发，它将被从ChannelPipeline 的头部开始一直被传播到Channel Pipeline 的尾端。Netty 总是将ChannelPipeline 的入站口作为头部，而将出站口作为尾端。 在ChannelPipeline 传播事件时，它会测试ChannelPipeline 中的下一个ChannelHandler 的类型是否和事件的运动方向相匹配。如果不匹配，ChannelPipeline 将跳过该ChannelHandler 并前进到下一个，直到它找到和该事件所期望的方向相匹配的为止。

修改ChannelPipeline

ChannelHandler 可以通过添加、删除或者替换其他的ChannelHandler 来实时地修改ChannelPipeline 的布局。（它也可以将它自己从ChannelPipeline 中移除。）这是ChannelHandler 最重要的能力之一，所以我们将仔细地来看看它是如何做到的。
addXXX 将一个ChannelHandler 添加到ChannelPipeline 中
remove 将一个ChannelHandler 从ChannelPipeline 中移除
replace 将ChannelPipeline 中的一个ChannelHandler 替换为另一个ChannelHandler
是不是和链表操作很像。其实ChannelPipeline就是ChannelHandler 构成的，这个已经强调很多遍了。

ChannelHandler 的执行和阻塞

通常ChannelPipeline 中的每一个ChannelHandler 都是通过它的EventLoop（I/O 线程）来处理传递给它的事件的。所以至关重要的是不要阻塞这个线程，因为这会对整体的I/O 处理产生负面的影响。但有时可能需要与那些使用阻塞API 的遗留代码进行交互。对于这种情况，ChannelPipeline 有一些接受一个EventExecutorGroup 的add()方法。如果一个事件被传递给一个自定义的EventExecutorGroup。它将被包含在这个EventExecutorGroup 中的某个EventExecutor 所处理，从而被从该
Channel 本身的EventLoop 中移除。对于这种用例，Netty 提供了一个叫DefaultEventExecutorGroup 的默认实现。

触发事件

ChannelPipeline 的API 公开了用于调用入站和出站操作的附加方法。下面是入站操作，用于通知ChannelInboundHandler 在ChannelPipeline 中所发生的事件。可能这些有的会用过。

fireChannelRegistered 调用ChannelPipeline 中下一个ChannelInboundHandler 的
channelRegistered(ChannelHandlerContext)方法
fireChannelUnregistered 调用ChannelPipeline 中下一个ChannelInboundHandler 的channelUnRegistered(ChannelHandlerContext)方法
fireChannelActive 调用ChannelPipeline 中下一个ChannelInboundHandler 的channelActive(ChannelHandlerContext)方法
fireChannelInactive 调用ChannelPipeline 中下一个ChannelInboundHandler 的channelInactive(ChannelHandlerContext)方法
fireExceptionCaught 调用ChannelPipeline 中下一个ChannelInboundHandler 的exceptionCaught(ChannelHandlerContext,Throwable)方法
fireUserEventTriggered 调用ChannelPipeline 中下一个ChannelInboundHandler 的userEventTriggered(ChannelHandlerContext,Object)方法
fireChannelRead 调用ChannelPipeline 中下一个ChannelInboundHandler 的channelRead(ChannelHandlerContext, Object msg)方法
fireChannelReadComplete 调用ChannelPipeline 中下一个ChannelInboundHandler 的channelReadComplete(ChannelHandlerContext)方法
fireChannelWritabilityChanged 调用ChannelPipeline 中下一个ChannelInboundHandler 的channelWritabilityChanged(ChannelHandlerContext)方法
其实不难发现，firexxx指的是调用链结构中的下一个ChannelHandler方法，而xxx就是方法名。这个其实比较简单，一样的，以集合类比，就是 触发下一个元素的事件。

在出站这边，处理事件将会导致底层的套接字上发生一系列的动作。下面是出站操作。

bind 将Channel 绑定到一个本地地址，这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的bind(ChannelHandlerContext, SocketAddress, ChannelPromise)方法

connect 将Channel 连接到一个远程地址，这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的connect(ChannelHandlerContext, SocketAddress, ChannelPromise)方法

disconnect 将Channel 断开连接。这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的disconnect(ChannelHandlerContext, Channel Promise)方法

close 将Channel 关闭。这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的close(ChannelHandlerContext, ChannelPromise)方法

deregister 将Channel 从它先前所分配的EventExecutor（即EventLoop）中注销。这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的deregister
(ChannelHandlerContext, ChannelPromise)方法

flush 冲刷Channel所有挂起的写入。这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的flush(ChannelHandlerContext)方法

write 将消息写入Channel。这将调用ChannelPipeline 中的下一个ChannelOutboundHandler的write(ChannelHandlerContext, Object msg, ChannelPromise)方法。注意：这并不会将消息写入底层的Socket，而只会将它放入队列中。要将它写入Socket，需要调用flush()或者writeAndFlush()方法

writeAndFlush 这是一个先调用write()方法再接着调用flush()方法的便利方法

read 请求从Channel 中读取更多的数据。这将调用ChannelPipeline 中的下一个ChannelOutboundHandler 的read(ChannelHandlerContext)方法

总结一下：
ChannelPipeline 保存了与Channel 相关联的ChannelHandler；
ChannelPipeline 可以根据需要，通过添加或者删除ChannelHandler 来动态地修改；
ChannelPipeline 有着丰富的API 用以被调用，以响应入站和出站事件。

ChannelHandlerContext

ChannelHandlerContext 代表了ChannelHandler 和ChannelPipeline 之间的关联，每当有ChannelHandler 添加到ChannelPipeline 中时，都会创ChannelHandlerContext。ChannelHandlerContext 的主要功能是管理它所关联的ChannelHandler 和在同一个ChannelPipeline 中的其他ChannelHandler 之间的交互。
ChannelHandlerContext 有很多的方法，其中一些方法也存在于Channel 和ChannelPipeline 本身上，但是有一点重要的不同。如果调用Channel 或者ChannelPipeline 上的这些方法，它们将沿着整个ChannelPipeline 进行传播。而调用位于ChannelHandlerContext上的相同方法，则将从当前所关联ChannelHandler 开始，并且只会传播给位于该ChannelPipeline 中的下一个能够处理该事件的ChannelHandler。
下面是ChannelHandlerContext的方法
alloc 返回和这个实例相关联的Channel 所配置的ByteBufAllocator
bind 绑定到给定的SocketAddress，并返回ChannelFuture
channel 返回绑定到这个实例的Channel
close 关闭这个实例，并返回ChannelFuture
connect 连接给定的SocketAddress，并返回ChannelFuture
deregister 从之前分配的EventExecutor 注销，并返回ChannelFuture
disconnect 从远程节点断开，并返回ChannelFuture
executor 返回调度事件的EventExecutor
fireChannelActive 触发对下一个ChannelInboundHandler 上的channelActive()方法（已连接）的调用
fireChannelInactive 触发对下一个ChannelInboundHandler 上的channelInactive()方法（已关闭）的调用
fireChannelRead 触发对下一个ChannelInboundHandler 上的channelRead()方法（已接收的消息）的调用
fireChannelReadComplete 触发对下一个ChannelInboundHandler 上的channelReadComplete()方法的调用
fireChannelRegistered 触发对下一个ChannelInboundHandler 上的fireChannelRegistered()方法的调用
fireChannelUnregistered 触发对下一个ChannelInboundHandler 上的fireChannelUnregistered()方法的调用
fireChannelWritabilityChanged 触发对下一个ChannelInboundHandler 上的fireChannelWritabilityChanged()方法的调用
fireExceptionCaught 触发对下一个ChannelInboundHandler 上的fireExceptionCaught(Throwable)方法的调用
handler 返回绑定到这个实例的ChannelHandler
isRemoved 如果所关联的ChannelHandler 已经被从ChannelPipeline中移除则返回true
name 返回这个实例的唯一名称、
pipeline 返回这个实例所关联的ChannelPipeline
read 将数据从Channel读取到第一个入站缓冲区；如果读取成功则触发一个channelRead事件，并（在最后一个消息被读取完成后）通知ChannelInboundHandler 的channelReadComplete(ChannelHandlerContext)方法
write 通过这个实例写入消息并经过ChannelPipeline
writeAndFlush 通过这个实例写入并冲刷消息并经过ChannelPipeline

当使用ChannelHandlerContext 的API 的时候，请牢记以下两点：
ChannelHandlerContext 和ChannelHandler 之间的关联（绑定）是永远不会改变的，所以缓存对它的引用是安全的；
相对于其他类的同名方法，ChannelHandler Context的方法将产生更短的事件流，应该尽可能地利用这个特性来获得最大的性能。

使用ChannelHandlerContext

当每一个ChannelHandler进入到ChannelPipeline的时候，此时就会有一个ChannelHandlerContext被创建。

@Override
    public void read(ChannelHandlerContext ctx) throws Exception {
        Channel channel = ctx.channel();
        channel.write(Unpooled.copiedBuffer("Netty in Action",
                CharsetUtil.UTF_8));
        super.read(ctx);
    }

通过channel方法获取到Channel，然后利用write方法写入数据。这是pipeline方法写入

        ChannelPipeline pipeline = ctx.pipeline();
        pipeline.write(Unpooled.copiedBuffer("Netty in Action",
                CharsetUtil.UTF_8));

虽然被调用的Channel 或ChannelPipeline 上的write()方法将一直传播事件通
过整个ChannelPipeline，但是在ChannelHandler 的级别上，事件从一个ChannelHandler到下一个ChannelHandler 的移动是由ChannelHandlerContext 上的调用完成的。

但是我们应该尽量减少传递，至少不应该将本不该这个hanlder处理的事件传递给这个hanlder。
要想调用从某个特定的ChannelHandler 开始的处理过程，必须获取到在（ChannelPipeline）该ChannelHandler 之前的ChannelHandler 所关联的ChannelHandlerContext。这个ChannelHandlerContext 将调用和它所关联的ChannelHandler 之后的ChannelHandler。

     ctx.write(Unpooled.copiedBuffer("Netty in Action",
                CharsetUtil.UTF_8));

消息将从下一个ChannelHandler 开始流经ChannelPipeline，绕过了所有前面的ChannelHandler。

ChannelHandler 和ChannelHandlerContext 的高级用法

你可以通过调用ChannelHandlerContext 上的pipeline()方法来获得被封闭的ChannelPipeline 的引用。这使得运行时得以操作ChannelPipeline 的ChannelHandler，我们可以利用这一点来实现一些复杂的设计。另一种高级的用法是缓存到ChannelHandlerContext 的引用以供稍后使用，这可能会发生在任何的ChannelHandler 方法之外，甚至来自于不同的线程。

   @Override
    public void handlerAdded(ChannelHandlerContext ctx) throws Exception {
        this.ctx = ctx;
        super.handlerAdded(ctx);
    }
    
    public void send(String msg){
        ctx.writeAndFlush(msg);
    }

先缓存我们的ChannelHandlerContext ctx，然后可以利用它发生消息。

因为一个ChannelHandler 可以从属于多个ChannelPipeline，所以它也可以绑定到多个ChannelHandlerContext 实例。

对于这种用法指在多个ChannelPipeline 中共享同一个ChannelHandler，对应的ChannelHandler 必须要使用@Sharable 注解标注；否则，试图将它添加到多个ChannelPipeline 时将会触发异常。显而易见，为了安全地被用于多个并发的Channel（即连接），这样的ChannelHandler 必须是线程安全的。

@ChannelHandler.Sharable
public class SharableHandler extends ChannelInboundHandlerAdapter{
    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
        System.out.println("Channel read message: " + msg);
        ctx.fireChannelRead(msg);
    }
}

前面的ChannelHandler 实现符合所有的将其加入到多个ChannelPipeline 的需求，
即它使用了注解@Sharable 标注，并且也不持有任何的状态。相反，书上也有错误的案例。

@ChannelHandler.Sharable
public class UnSharableHandler extends ChannelInboundHandlerAdapter {
    private int count;
    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) {
        count++;
        System.out.println("channelRead(...) called the "
                + count + " time");
        ctx.fireChannelRead(msg);
    }
}

这段代码的问题在于它拥有状态，即用于跟踪方法调用次数的实例变量count。将这个类的一个实例添加到ChannelPipeline将极有可能在它被多个并发的Channel访问时导致问题。（当然，这个简单的问题可以通过使channelRead()方法变为同步方法来修正。）总之，只应该在确定了你的ChannelHandler 是线程安全的时才使用@Sharable 注解。

为何要共享同一个ChannelHandler 在多个ChannelPipeline中安装同一个ChannelHandler的一个常见的原因是用于收集跨越多个Channel 的统计信息。

异常处理

异常处理是任何真实应用程序的重要组成部分，它也可以通过多种方式来实现。因此，Netty提供了几种方式用于处理入站或者出站处理过程中所抛出的异常。

处理入站异常

其实处理异常非常简单，之前曾经写过一个方法，叫做exceptionCaught，先看默认实现。

 /**
     * Calls {@link ChannelHandlerContext#fireExceptionCaught(Throwable)} to forward
     * to the next {@link ChannelHandler} in the {@link ChannelPipeline}.
     *
     * Sub-classes may override this method to change behavior.
     */
    @Skip
    @Override
    @SuppressWarnings("deprecation")
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause)
            throws Exception {
        ctx.fireExceptionCaught(cause);
    }

这个看起来很简单，就是firexxx，就是往下传递嘛，那么意思就是向下传递这个异常，但是我可以重写，例如：关闭channel，捕获等操作。当然了如果他传输到了尾端还没有处理，则会被标记为未处理异常。

处理出站异常

每个出站操作都将返回一个ChannelFuture。注册到ChannelFuture 的ChannelFutureListener 将在操作完成时被通知该操作是成功了还是出错了。
几乎所有的ChannelOutboundHandler 上的方法都会传入一个ChannelPromise的实例。作为ChannelFuture 的子类，ChannelPromise 也可以被分配用于异步通知的监听器。但是，ChannelPromise 还具有提供立即通知的可写方法：

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

添加ChannelFutureListener 只需要调用ChannelFuture 实例上的addListener
(ChannelFutureListener)方法，并且有两种不同的方式可以做到这一点。其中最常用的方式是，调用出站操作（如write()方法）所返回的ChannelFuture 上的addListener()方法。

  @Override
    public void write(ChannelHandlerContext ctx, Object msg,
                      ChannelPromise promise) {
        promise.addListener(new ChannelFutureListener() {
            @Override
            public void operationComplete(ChannelFuture f) {
                if (!f.isSuccess()) {
                    f.cause().printStackTrace();
                    f.channel().close();
                }
            }
        });
    }

第二种方式是将ChannelFutureListener 添加到即将作为参数传递给ChannelOutboundHandler的方法的ChannelPromise。

    @Override
    public void write(ChannelHandlerContext ctx, Object msg,
                      ChannelPromise promise) {
        promise.addListener(new ChannelFutureListener() {
            @Override
            public void operationComplete(ChannelFuture f) {
                if (!f.isSuccess()) {
                    f.cause().printStackTrace();
                    f.channel().close();
                }
            }
        });
    }

ChannelPromise 的可写方法
通过调用ChannelPromise 上的setSuccess()和setFailure()方法，可以使一个操作的状态在ChannelHandler 的方法返回给其调用者时便即刻被感知到。

结束语

这一次我们仔细地研究了Netty 的数据处理组件—ChannelHandler。我们讨论了
ChannelHandler 是如何链接在一起，以及它们是如何作为ChannelInboundHandler 和ChannelOutboundHandler 与ChannelPipeline 进行交互的。