深入Jetty源码之Buffer

public  interface Buffer  extends Cloneable {
     //  基于Buffer主要用于向当前连接读写数据，因而它定义了两个核心的方法：readFrom和writeTo。其中readFrom方法从InputStream中读取字节数据，writeTo方法将响应字节写入OutputStream中，即向Connection中读取和写入数据，写完后清理当前Buffer。
     int readFrom(InputStream in,  int max)  throws IOException;
     void writeTo(OutputStream out)  throws IOException;

     //  在Buffer从InputStream（Connection）中读取数据后，Buffer接口还提供了很多不同的方法用于从Buffer中读取或写入字节数据。

     //  Jetty中的Buffer是一个FIFO的字节队列，它的设计类似NIO中Buffer的设计：每次get操作都从getIndex开始，并且getIndex会向前移动读取的字节数的长度；每次的peek操作也getIndex开始，但是peek操作不会使getIndex向前移动；每次put操作都从putIndex开始，并且putIndex会向前移动写入的字节数的长度；每次poke操作也会从putIndex开始，但是poke操作不会使putIndex向前移动；mark操作会以getIndex作为基准设置markIndex的值，从而在reset时会将getIndex重置到之前mark过的位置；capacity表示该Buffer最多可存储的字节数，而length表示从getIndex到putIndex还存在的字节数。并且Buffer永远保证以下关系总是成立：markIndex<=getIndex<=putIndex<=capacity

     byte get();
     int get( byte[] b,  int offset,  int length);
    Buffer get( int length);
     int getIndex();

     void mark();
     void mark( int offset);
     int markIndex();

     byte peek();
     byte peek( int index);
    Buffer peek( int index,  int length);
     int peek( int index,  byte[] b,  int offset,  int length);

     int poke( int index, Buffer src);
     void poke( int index,  byte b);
     int poke( int index,  byte b[],  int offset,  int length);

     int put(Buffer src);
     void put( byte b);
     int put( byte[] b, int offset,  int length);
     int put( byte[] b);
     int putIndex();

     int length();
     void clear();
     void reset();
     void setGetIndex( int newStart);
     void setMarkIndex( int newMark);
     void setPutIndex( int newLimit);

     //  一个Buffer还有独立的两种状态：access级别和volatile。
access级别有：IMMUTABLE，表示当前Buffer所有的Index和内容都不能被改变；READONLY，表示当前Buffer是只读的，即getIndex和markIndex可以被改变，而putIndex以及Buffer内容不可以；READWRITE，表示所有的Index以及Buffer的内容可以被改变。
volatile状态表示当前Buffer是否会通过其他路径被修改，默认情况下，ByteArrayBuffer、DirectNIOBuffer等是NON_VOLATILE状态，而View是VOLATILE状态（除非View内部的Buffer是IMMUTABLE）。VOLATILE的状态感觉不是一个比较严谨的概念，比如对一个View它是VOLATILE的，但是在这种情况下，它内部包装的Buffer应该也变成VOLATILE状态，并且在所有的View被回收后，其内部包装的Buffer应该重新变成NON_VOLATILE状态。要实现这种严谨逻辑应该是可以做的到的，只是会比较麻烦，而且貌似也没必要，因而Jetty并没有尝试着去这样做。

     //  返回包含当前Buffer从getIndex到putIndex内容的Buffer，并且返回的Buffer不可以被其他路径修改。如果当前Buffer是NON_VOLATILE，则直接返回当前Buffer（这个实现是不严谨的，因为在这种情况下，其实有两个Buffer实例可以修改同一份数据），否则，克隆一个新的Buffer，这样对新的Buffer的修改不会影响原Buffer的内容。
    Buffer asNonVolatileBuffer();
     //  返回一个只读的Buffer（View），该只读的Buffer的读取不会影响原来Buffer的Index。
    Buffer asReadOnlyBuffer();
     //  拷贝一个不可修改的ByteBuffer。
    Buffer asImmutableBuffer();
     //  返回一个可修改的Buffer，并且对返回的Buffer的内容修改会影响原有的Buffer。
    Buffer asMutableBuffer();

     //  当前Buffer是否不可被修改，即Buffer内容和所有Index都不能被修改。
     boolean isImmutable();
     //  当前Buffer是否是只读的。
     boolean isReadOnly();
     //  是否当前Buffer内容可以通过其他路径被修改，比如View一般情况下是VOLATILE状态（除非View内部的Buffer是IMMUTABLE）。
    boolean isVolatile();
    
     //  除了以上的操作，Buffer还提供了一些其他用于操作Buffer内部字节的方法：

     // 如果内部使用字节数组表示，返回该字节数组，否则，返回null。
     byte[] array();
     //  获取从getIndex到putIndex的字节数组，其长度为length。
     byte[] asArray();
     //  如果当前Buffer是对另一个Buffer的包装，则返回内部被包装的Buffer实例，否则返回当前Buffer本身。
    Buffer buffer();

     int capacity();
     //  返回当前Buffer剩余的空间，即capacity－putIndex。
     int space();
     //  清除Buffer内容，即设置getIndex和putIndex为0，以及markIndex为-1。
     //  整理Buffer内容，即将markIndex >= 0 ? min(getIndex, markIndex) : getIndex到putIndex的内容移动到Buffer的起始位置，同时修改相应的getIndex、markIndex、putIndex。
     void compact();
     //  当前Buffer是否有可用字节，即是否putIndex>getIndex。
     boolean hasContent();

     //  跳过n个字节，即getIndex增加min(remaining(), n)的值。
     int skip( int n);

     //  切割出当前Buffer从getIndex到putIndex的View，一般来说它是volatile的（除非它是immutable类型的Buffer）。
    Buffer slice();
     //  切割出当前Buffer从markIndex到putIndex的View，一般来说它是volatile的（除非它是immutable类型的Buffer）。
    Buffer sliceFromMark();
    Buffer sliceFromMark( int length);

     //  返回包含当前Buffer状态和内容的字符串。
    String toDetailString();
     boolean equalsIgnoreCase(Buffer buffer);
 }