Netty 异步的、事件驱动的网络应用程序框架和工具

/**
 * ByteBuf是一个连续随机访问的bytes序列，是原始byte数组及ByteBuffer的顶层抽象。
 *
 * buffer创建：
 * 推荐使用工具类Unpooled中的方法进行创建，也可以调用实现类的构造方法创建。
 *
 * 随机访问索引：
 * 和通常的原始byte数组一样，ByteBuf使用基于0的索引，即第一个字节的索引为0，最后一个字节的索引为 capacity - 1，
 *
 * ByteBuf buffer = ...;
 * for (int i = 0; i < buffer.capacity(); i ++) {
 *     byte b = buffer.getByte(i);
 *     System.out.println((char) b);
 * }
 *
 * 连续访问索引：
 * ByteBuf提供两个指针变量readerIndex、writerIndex分别用于读写操作，如下图表，两个变量将
 * ByteBuf分割为三部分。
 *
 *      +-------------------+------------------+------------------+
 *      | discardable bytes |  readable bytes  |  writable bytes  |
 *      |                   |     (CONTENT)    |                  |
 *      +-------------------+------------------+------------------+
 *      |                   |                  |                  |
 *      0      <=      readerIndex   <=   writerIndex    <=    capacity
 *
 * 可读取的字节（实际存储的内容）：
 * 这一部分是数据实际存储的位置，read和skip方法就是在这块数据上执行获取和跳过操作，同时read操
 * 作会增加可读取字节数。如果read操作的参数是一个ByteBuf，并且未指定存储位置，则参数ByteBuf
 * 的writeIndex 也会随着增长。
 *
 * 可读取的数据不足会抛出IndexOutOfBoundsException异常，新分配内存，包装或复制的buffer的
 * readerIndex为0.
 *
 * 遍历buffer；
 *
 * ByteBuf buffer = ...;
 * while (buffer.isReadable()) {
 *     System.out.println(buffer.readByte());
 * }
 *
 * 可写入字节： *
 * 这一部分是需要填充的未定义空间，write方法会从当前writeIndex位置写入数据并增加writeIndex值，
 * 如果参数是ByteBuf且并未指定源索引，则参数ByteBuf的readerIndex也会随着增长。
 *
 * 如果当前可写空间不足，则抛出IndexOutOfBoundsException异常，新分配内存，包装或复制的buffer
 * 的writerIndex为buffe的capacity容量。

 * 随机填充
 * ByteBuf buffer = ...;
 * while (buffer.maxWritableBytes() >= 4) {
 *     buffer.writeInt(random.nextInt());
 * }
 *
 * 可废弃字节：
 * 这一部分为已经执行过读取操作的数据，初始空间为0，随着read操作的执行，最大增长至writeIndex值。
 * 可废弃字节可以通过调用discardReadBytes()来丢弃，并重新标识为未使用。如下所示：

 *  discardReadBytes()执行之前：
 *
 *      +-------------------+------------------+------------------+
 *      | discardable bytes |  readable bytes  |  writable bytes  |
 *      +-------------------+------------------+------------------+
 *      |                   |                  |                  |
 *      0      <=      readerIndex   <=   writerIndex    <=    capacity
 *
 *
 *  discardReadBytes()执行之后：
 *
 *      +------------------+--------------------------------------+
 *      |  readable bytes  |    writable bytes (got more space)   |
 *      +------------------+--------------------------------------+
 *      |                  |                                      |
 * readerIndex (0) <= writerIndex (decreased)        <=        capacity
 *
 * 需要注意的是，通常情况下，discardReadBytes（）操作无法保证buffer的可写数据。根据同的buffer
 * 实现，大多数情况下，可写数据空间不会被移动，甚至会被完全不同的数据填充。
 *
 * 清除索引:
 * clear()方法可以将buffer的readerIndex和writeIndex都置为0，但是并不清除buffer的数据，
 * 另外需要注意是区分和ByteBuffer#clear()方法的不同。
 * <h4>Clearing the buffer indexes</h4>
 *
 * <pre>
 *  clear()执行之前：
 *
 *      +-------------------+------------------+------------------+
 *      | discardable bytes |  readable bytes  |  writable bytes  |
 *      +-------------------+------------------+------------------+
 *      |                   |                  |                  |
 *      0      <=      readerIndex   <=   writerIndex    <=    capacity
 *
 *
 *  clear()执行之后：
 *
 *      +---------------------------------------------------------+
 *      |             writable bytes (got more space)             |
 *      +---------------------------------------------------------+
 *      |                                                         |
 *      0 = readerIndex = writerIndex            <=            capacity
 *
 * 查询操作：
 * 单字节查询可以使用 indexOf(int, int, byte) 方法，bytesBefore(int, int, byte)
 * 方法对于处理null结尾的字符串会特别有用。
 * 复杂查询可以使用 forEachByte(int, int, ByteProcessor) 方法（ByteProcessor 提供遍历字节集合机制， 方法中使用ByteProcessor的特定实现类）
 *
 * 标记和重置：
 * ByteBuf中存在两种标记变量，分别用于存储readerIndex和writerIndex，可以通过调用reset()
 * 方法来重置任意其一。除了没有readlimit变量，ByteBuf和InputStream具有相同的标记和和重置操作机制，
 *
 * 衍生buffer：
 * 通过调用ByteBuf的以下方法可以创建一个已知buffer的镜像视图。
 *
 * #duplicate()
 * #slice()
 * #slice(int, int)
 * #readSlice(int)
 * #retainedDuplicate()
 * #retainedSlice()
 * #retainedSlice(int, int)
 * #readRetainedSlice(int)
 *
 * buffer视图虽然和源buffer共享同一块儿内存，但是拥有完全独立的readerIndex，writeIndex和标记索引。
 * 这和NIO buffer机制非常相似。
 *
 * 如果要获取一份全新的buffer备份，可以执行buffer的copy()方法。
 *
 * <h4>Non-retained and retained derived buffers</h4>
 *
 * duplicate()、slice(int, int)、readSlice(int)并未在新生成的衍生buffer执行retain()操作，因此
 * 衍生buffer的引用计数没有增长。retainedDuplicate()、retainedSlice()、readRetainedSlice()
 * 方法可以生成一个包含引用计数增长并且产生较少垃圾（）的衍生buffer。
 *
 * JDK byte array转换
 *
 * Byte array
 *
 * 由byte数组（byte[]）包装生成的ByteBuf，可以直接通过数据中的方法进行操作。
 * 判断方法：hasArray()。
 *
 * NIO Buffers
 * 如果一个ByteBuf可以被转换为NIO ByteBuffer，那么就可以通过nioBuffer的方法来操作ByteBuf。
 * 判断方法：nioBufferCount（）。
 *
 * 字符串输出：
 * ByteBuf存在多种toString()方法，需要注意的是toString()方法并不是一个转换方法。
 *
 * I/O Streams
 *
 * 详见 缓冲输入输出流 ByteBufInputStream  ByteBufOutputStream.
 */