Netty——ByteBuf的API

ByteBuf

正如前面所提到的，网络数据的基本单位总是字节。Java NIO 提供了 ByteBuffer 作为它的字节容器，但是这个类使用起来过于复杂，而且也有些繁琐。
Netty 的 ByteBuffer 替代品是 ByteBuf，一个强大的实现，既解决了 JDK API 的局限性，又为网络应用程序的开发者提供了更好的 API。

Netty 的数据处理 API 通过两个组件暴露——abstract class ByteBuf 和 interface ByteBufHolder。

优点：

它可以被用户自定义的缓冲区类型扩展；
通过内置的复合缓冲区类型实现透明的零拷贝；
容量可以按需增长（类似于JDK的StringBuilder）；
在读和写这两种模式之间切换不需要调用ByteBuffer的Flip()方法；
读和写使用了不同的索引；
支持方法的链式调用；
支持引用计数；
支持池化；

工作原理：

ByteBuf 维护了两个不同的索引:一个用于读取，一个用于写入。当你从 ByteBuf 读取时，它的 readerIndex 将会被递增已经被读取的字节数。同样地，当你写入 ByteBuf 时，它的 writerIndex 也会被递增。

要了解这些索引两两之间的关系，请考虑一下，如果打算读取字节直到 readerIndex 达到和 writerIndex 同样的值时会发生什么。在那时，你将会到达“可以读取的”数据的末尾。就如同试图读取超出数组末尾的数据一样，试图读取超出该点的数据将会触发一个 IndexOutOf- BoundsException。

名称以 read 或者 write 开头的 ByteBuf 方法，将会推进其对应的索引，而名称以 set 或者 get 开头的操作则不会。后面的这些方法将在作为一个参数传入的一个相对索引上执行操作。

可以指定 ByteBuf 的最大容量。试图移动写索引(即 writerIndex)超过这个值将会触发一个异常1。(默认的限制是 Integer.MAX_VALUE。)

ByteBuf的使用模式

1. 堆缓冲区：

最常用的 ByteBuf 模式是将数据存储在 JVM 的堆空间中。这种模式被称为支撑数组 (backing array)，它能在没有使用池化的情况下提供快速的分配和释放。这种方式，非常适合于有遗留的数据需要处理的情况。

ByteBuf heapBuf = ...;//检查ByteBuf是有一个支持数组if (heapBuf.hasArray()) {//如果有则获该数组的引用byte[] array = heapBuf.array();//计算第一个字节的偏移量int offset = heapBuf.arrayOffset() + heapBuf.readerIndex();//获得可读字节数int length = heapBuf.readableBytes();//使用数组、偏移量和长度作为参数调用方法handleArray(array, offset, length);}

注意：当hasArray()方法返回false时，尝试访问支持数组将处罚一个UnsupportedOperationException。这个模式类似于JDK的ByteBuffer的用法。

2. 直接缓冲区：

ByteBuffer的Javadoc1明确指出:“直接缓冲区的内容将驻留在常规的会被垃圾回收的堆之外。”这也就解释了为何直接缓冲区对于网络数据传输是理想的选择。如果你的数据包含在一个在堆上分配的缓冲区中，那么事实上，在通过套接字发送它之前，JVM将会在内部把你的缓冲区复制到一个直接缓冲区中。

直接缓冲区的主要缺点是，相对于基于堆的缓冲区，它们的分配和释放都较为昂贵。如果你正在处理遗留代码，你也可能会遇到另外一个缺点:因为数据不是在堆上，所以你不得不进行一次复制：

 ByteBuf directBuf = ...;//检查ByteBuf是否由数组支撑。如果不是，则这是一个直接缓冲区if (!directBuf.hasArray()) {//获取可读字节数int length = directBuf.readableBytes();//分配一个新的数组来保存具有该长度的字节数据byte[] array = new byte[length];//将字节复制到该数组directBuf.getBytes(directBuf.readerIndex(), array);//调用方法handleArray(array, 0, length);}

3. 复合缓冲区：
第三种也是最后一种模式使用的是复合缓冲区，它为多个 ByteBuf 提供一个聚合视图。在这里你可以根据需要添加或者删除 ByteBuf 实例，这是一个 JDK 的 ByteBuffer 实现完全缺失的特性。

Netty 通过一个 ByteBuf 子类CompositeByteBuf实现了这个模式，它提供了一个将多个缓冲区表示为单个合并缓冲区的虚拟表示。

注意：CompositeByteBuf中的ByteBuf实例可能同时包含直接内存分配和非直接内存分配。如果其中只有一个实例，那么对 CompositeByteBuf 上的 hasArray()方法的调用将返回该组件上的 hasArray()方法的值;否则它将返回 false。

字节级操作

随机访问索引：
如同在普通的 Java 字节数组中一样，ByteBuf 的索引是从零开始的:第一个字节的索引是 0，最后一个字节的索引总是 capacity() - 1。

ByteBuf buffer = Unpooled.copiedBuffer("hello world!", Charset.forName("UTF-8"));for (int i = 0; i < buffer.capacity(); i++) {byte b = buffer.getByte(i);System.out.println((char)b);}

需要注意的是，使用那些需要一个索引值参数的方法(的其中)之一来访问数据既不会改变 readerIndex 也不会改变 writerIndex。如果有需要，也可以通过调用 readerIndex(index) 或者 writerIndex(index)来手动移动这两者。

顺序访问索引：

ByteBuf 同时具有读索引和写索引，下图展示了 ByteBuf 是如何被它的两个索引划分成 3 个区域的。

可丢弃字节：

标记为可丢弃字节的分段包含了已经被读过的字节。通过调用 discardReadBytes()方法，可以丢弃它们并回收空间。这个分段的初始大小为 0，存储在 readerIndex 中，会随着 read 操作的执行而增加(get*操作不会移动 readerIndex)。

下图所展示的缓冲区上调用discardReadBytes()方法后的结果。可以看到，可丢弃字节分段中的空间已经变为可写的了。注意，在调用discardReadBytes()之后，对可写分段的内容并没有任何的保证。

虽然你可能会倾向于频繁地调用 discardReadBytes()方法以确保可写分段的最大化，但是请注意，这将极有可能会导致内存复制，因为可读字节(图中标记为 CONTENT 的部分)必须被移动到缓冲区的开始位置。我们建议只在有真正需要的时候才这样做，例如，当内存非常宝贵的时候。

可读字节：

ByteBuf 的可读字节分段存储了实际数据。新分配的、包装的或者复制的缓冲区的默认的 readerIndex 值为 0。任何名称以 read 或者 skip 开头的操作都将检索或者跳过位于当前 readerIndex 的数据，并且将它增加已读字节数。

如果被调用的方法需要一个 ByteBuf 参数作为写入的目标，并且没有指定目标索引参数，那么该目标缓冲区的 writerIndex 也将被增加，例如:

readBytes(ByteBuf dest);

如果尝试在缓冲区的可读字节数已经耗尽时从中读取数据，那么将会引发一个 IndexOutOfBoundsException。

可写字节:

可写字节分段是指一个拥有未定义内容的、写入就绪的内存区域。新分配的缓冲区的 writerIndex 的默认值为 0。任何名称以 write 开头的操作都将从当前的 writerIndex 处开始写数据，并将它增加已经写入的字节数。如果写操作的目标也是 ByteBuf，并且没有指定源索引的值，则源缓冲区的 readerIndex 也同样会被增加相同的大小。这个调用如下所示:

writeBytes(ByteBuf dest)

如果尝试往目标写入超过目标容量的数据，将会引发一个IndexOutOfBoundException。

索引管理：

JDK 的 InputStream 定义了 mark(int readlimit)和 reset()方法，这些方法分别被用来将流中的当前位置标记为指定的值，以及将流重置到该位置。

同样，可以通过调用 markReaderIndex()、markWriterIndex()、resetWriterIndex() 和 resetReaderIndex()来标记和重置 ByteBuf 的 readerIndex 和 writerIndex。这些和 InputStream 上的调用类似，只是没有 readlimit 参数来指定标记什么时候失效。

也可以通过调用 readerIndex(int)或者 writerIndex(int)来将索引移动到指定位置。试图将任何一个索引设置到一个无效的位置都将导致一个 IndexOutOfBoundsException。
可以通过调用 clear()方法来将 readerIndex 和 writerIndex 都设置为 0。注意，这并不会清除内存中的内容。

下图展示了在 clear()方法被调用之后 ByteBuf
的状态。

调用 clear()比调用 discardReadBytes()轻量得多，因为它将只是重置索引而不会复制任何的内存。

查找操作：

在ByteBuf中有多种可以用来确定指定值的索引的方法。最简单的是使用indexOf()方法。较复杂的查找可以通过那些需要一个ByteBufProcessor（4.1版本废弃，使用ByteProcessor）作为参数的方法达成。这个接口只定义了一个方法:

//它将检查输入值是否是正在查找的值。
boolean prcess(byte value)

ByteBufProcessor针对一些常见的值定义了许多便利的方法。假设你的应用程序需要和所谓的包含有以NULL结尾的内容的Flash套接字集成。调用

forEachByte(ByteBufProcessor.FIND_NUL)

将简单高效地消费该 Flash 数据，因为在处理期间只会执行较少的边界检查。

//查找回车符\r
ByteBuf buffer = ...;
int index = buffer.forEachByte(ByteBufProcessor.FIND_CR);

派生缓冲区：
派生缓冲区为 ByteBuf 提供了以专门的方式来呈现其内容的视图。这类视图是通过以下方法被创建的:

duplicate();
slice();
slice(int, int);
Unpooled.unmodifiableBuffer(…);
order(ByteOrder);
readSlice(int)。

每个这些方法都将返回一个新的 ByteBuf 实例，它具有自己的读索引、写索引和标记索引。其内部存储和 JDK 的 ByteBuffer 一样也是共享的。这使得派生缓冲区的创建成本是很低廉的，但是这也意味着，如果你修改了它的内容，也同时修改了其对应的源实例，所以要小心。

//对ByteBuf进行切片Charset utf8 = Charset.forName("UTF-8");ByteBuf buf = Unpooled.copiedBuffer("Netty in Action rocks!", utf8);ByteBuf slice = buf.slice(0, 15);System.out.println(slice.toString(utf8));//更新索引0处的字节buf.setByte(0, (byte)'J');//数据是共享的assert buf.getByte(0) == slice.getByte(0);

复制：

如果需要一个现有缓冲区的真实副本，请使用 copy()或者 copy(int, int)方法。不同于派生缓冲区，由这个调用所返回的 ByteBuf 拥有独立的数据副本。

//对ByteBuf进行复制Charset utf8 = Charset.forName("UTF-8");ByteBuf buf = Unpooled.copiedBuffer("Netty in Action rocks!", utf8);ByteBuf copy = buf.copy(0, 15);System.out.println(copy.toString(utf8));//更新索引0处的字节buf.setByte(0, (byte)'J');//数据不是共享的assert buf.getByte(0) != copy.getByte(0);

读写操作

有两种类别的读/写操作:

get()和 set()操作，从给定的索引开始，并且保持索引不变;
read()和 write()操作，从给定的索引开始，并且会根据已经访问过的字节数对索引进行调整。

get操作：

set操作：

//get()和set()的用法Charset utf8 = Charset.forName("UTF-8");ByteBuf buf = Unpooled.copiedBuffer("Netty in Action rocks!", utf8);//打印第一个字符NSystem.out.println((char)buf.getByte(0));int readerIndex = buf.readerIndex();int writerIndex = buf.writerIndex();buf.setByte(0, (byte)'B');System.out.println((char)buf.getByte(0));System.out.println(readerIndex);System.out.println(writerIndex);

read()操作：
其作用于当前的 readerIndex 或 writerIndex。这些方法将用于从 ByteBuf 中读取数据，如同它是一个流。

write()操作：

Charset utf8 = Charset.forName("UTF-8");ByteBuf buf = Unpooled.copiedBuffer("Netty in Action rocks!", utf8);//打印第一个字符NSystem.out.println((char)buf.readByte());int readerIndex = buf.readerIndex();int writerIndex = buf.writerIndex();System.out.println(readerIndex);System.out.println(writerIndex);buf.writeByte((char)'?');System.out.println(buf.readerIndex());System.out.println(buf.writerIndex());

其他操作：

ByteBufHolder接口

我们经常发现，除了实际的数据负载之外，我们还需要存储各种属性值。HTTP 响应便是一个很好的例子，除了表示为字节的内容，还包括状态码、cookie 等。

为了处理这种常见的用例，Netty 提供了 ByteBufHolder。ByteBufHolder 也为 Netty 的高级特性提供了支持，如缓冲区池化，其中可以从池中借用 ByteBuf，并且在需要时自动释放。

ByteBufHolder 只有几种用于访问底层数据和引用计数的方法。下表列出了它们(这里不包括它继承自 ReferenceCounted 的那些方法)。

如果想要实现一个将其有效负载存储在 ByteBuf 中的消息对象，那么 ByteBufHolder 将是个不错的选择。

ByteBuf分配

按需分配：ByteBufAllocator接口：

为了降低分配和释放内存的开销，Netty 通过 interface ByteBufAllocator 实现了 (ByteBuf 的)池化，它可以用来分配我们所描述过的任意类型的 ByteBuf 实例。使用池化是特定于应用程序的决定，其并不会以任何方式改变 ByteBuf API(的语义)。

可以通过 Channel(每个都可以有一个不同的 ByteBufAllocator 实例)或者绑定到 ChannelHandler 的 ChannelHandlerContext 获取一个到 ByteBufAllocator 的引用。

//从Channel获取一个到ByteBufAllocator的引用Channel channnel = null;ByteBufAllocator allocator = channnel.alloc();//从ChannelHandlerContext获取一个到ByteBufAllocator的引用ChannelHandlerContext ctx = null;ByteBufAllocator allocator1 = ctx.alloc();

Netty提供了两种ByteBufAllocator的实现:PooledByteBufAllocator和UnpooledByteBufAllocator。前者池化了ByteBuf的实例以提高性能并最大限度地减少内存碎片。此实现使用了一种称为 j e m a l l o c 的已被大量现代操作系统所采用的高效方法来分配内存。后者的实现不池化ByteBuf实例，并且在每次它被调用时都会返回一个新的实例。
虽然Netty默认 1 使用了PooledByteBufAllocator，但这可以很容易地通过ChannelConfig API或者在引导你的应用程序时指定一个不同的分配器来更改。

Unpooled缓冲区

可能某些情况下，你未能获取一个到 ByteBufAllocator 的引用。对于这种情况，Netty 提供了一个简单的称为 Unpooled 的工具类，它提供了静态的辅助方法来创建未池化的 ByteBuf 实例。

Unpooled 类还使得 ByteBuf 同样可用于那些并不需要 Netty 的其他组件的非网络项目，使得其能得益于高性能的可扩展的缓冲区 API。

ByteBufUtil类

ByteBufUtil 提供了用于操作 ByteBuf 的静态的辅助方法。因为这个 API 是通用的，并且和池化无关，所以这些方法已然在分配类的外部实现。

这些静态方法中最有价值的可能就是 hexdump()方法，它以十六进制的表示形式打印 ByteBuf 的内容。这在各种情况下都很有用，例如，出于调试的目的记录 ByteBuf 的内容。十六进制的表示通常会提供一个比字节值的直接表示形式更加有用的日志条目，此外，十六进制的版本还可以很容易地转换回实际的字节表示。

另一个有用的方法是boolean equals(ByteBuf, ByteBuf)，它被用来判断两个 ByteBuf 实例的相等性。如果你实现自己的 ByteBuf 子类，你可能会发现 ByteBufUtil 的其他有用方法。

引用计数

引用计数是一种通过在某个对象所持有的资源不再被其他对象引用时释放该对象所持有的资源来优化内存使用和性能的技术。Netty 在第 4 版中为 ByteBuf 和 ByteBufHolder 引入了引用计数技术，它们都实现了 interface ReferenceCounted。

引用计数背后的想法并不是特别的复杂;它主要涉及跟踪到某个特定对象的活动引用的数量。一个 ReferenceCounted 实现的实例将通常以活动的引用计数为 1 作为开始。只要引用计数大于 0，就能保证对象不会被释放。当活动引用的数量减少到 0 时，该实例就会被释放。注意，虽然释放的确切语义可能是特定于实现的，但是至少已经释放的对象应该不可再用了。

//从Channel获取ByteBufAllocatorChannel channel = null;ByteBufAllocator allocator = channel.alloc();//分配一个ByteBufByteBuf buffer = allocator.directBuffer();//检查引用计数是否为预期的1assert buffer.refCnt() == 1;

//减少到该对象的活动引用。当减少到0时，该对象被释放，并且该方法返回true
ByteBuf buffer = ...;
boolean released = buffer.release();
...

试图访问一个已经被释放的引用计数的对象，将会导致一个IllegalReferenceCountException。

注意，一个特定的(ReferenceCounted 的实现)类，可以用它自己的独特方式来定义它的引用计数规则。例如，我们可以设想一个类，其 release()方法的实现总是将引用计数设为零，而不用关心它的当前值，从而一次性地使所有的活动引用都失效。