View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.buffer;
17  
18  import io.netty.util.ReferenceCounted;
19  
20  import java.io.IOException;
21  import java.io.InputStream;
22  import java.io.OutputStream;
23  import java.nio.ByteBuffer;
24  import java.nio.ByteOrder;
25  import java.nio.channels.GatheringByteChannel;
26  import java.nio.channels.ScatteringByteChannel;
27  import java.nio.charset.Charset;
28  import java.nio.charset.UnsupportedCharsetException;
29  
30  /**
31   * A random and sequential accessible sequence of zero or more bytes (octets).
32   * This interface provides an abstract view for one or more primitive byte
33   * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}.
34   *
35   * <h3>Creation of a buffer</h3>
36   *
37   * It is recommended to create a new buffer using the helper methods in
38   * {@link Unpooled} rather than calling an individual implementation's
39   * constructor.
40   *
41   * <h3>Random Access Indexing</h3>
42   *
43   * Just like an ordinary primitive byte array, {@link ByteBuf} uses
44   * <a href="http://en.wikipedia.org/wiki/Zero-based_numbering">zero-based indexing</a>.
45   * It means the index of the first byte is always {@code 0} and the index of the last byte is
46   * always {@link #capacity() capacity - 1}.  For example, to iterate all bytes of a buffer, you
47   * can do the following, regardless of its internal implementation:
48   *
49   * <pre>
50   * {@link ByteBuf} buffer = ...;
51   * for (int i = 0; i &lt; buffer.capacity(); i ++) {
52   *     byte b = buffer.getByte(i);
53   *     System.out.println((char) b);
54   * }
55   * </pre>
56   *
57   * <h3>Sequential Access Indexing</h3>
58   *
59   * {@link ByteBuf} provides two pointer variables to support sequential
60   * read and write operations - {@link #readerIndex() readerIndex} for a read
61   * operation and {@link #writerIndex() writerIndex} for a write operation
62   * respectively.  The following diagram shows how a buffer is segmented into
63   * three areas by the two pointers:
64   *
65   * <pre>
66   *      +-------------------+------------------+------------------+
67   *      | discardable bytes |  readable bytes  |  writable bytes  |
68   *      |                   |     (CONTENT)    |                  |
69   *      +-------------------+------------------+------------------+
70   *      |                   |                  |                  |
71   *      0      <=      readerIndex   <=   writerIndex    <=    capacity
72   * </pre>
73   *
74   * <h4>Readable bytes (the actual content)</h4>
75   *
76   * This segment is where the actual data is stored.  Any operation whose name
77   * starts with {@code read} or {@code skip} will get or skip the data at the
78   * current {@link #readerIndex() readerIndex} and increase it by the number of
79   * read bytes.  If the argument of the read operation is also a
80   * {@link ByteBuf} and no destination index is specified, the specified
81   * buffer's {@link #writerIndex() writerIndex} is increased together.
82   * <p>
83   * If there's not enough content left, {@link IndexOutOfBoundsException} is
84   * raised.  The default value of newly allocated, wrapped or copied buffer's
85   * {@link #readerIndex() readerIndex} is {@code 0}.
86   *
87   * <pre>
88   * // Iterates the readable bytes of a buffer.
89   * {@link ByteBuf} buffer = ...;
90   * while (buffer.isReadable()) {
91   *     System.out.println(buffer.readByte());
92   * }
93   * </pre>
94   *
95   * <h4>Writable bytes</h4>
96   *
97   * This segment is a undefined space which needs to be filled.  Any operation
98   * whose name starts with {@code write} will write the data at the current
99   * {@link #writerIndex() writerIndex} and increase it by the number of written
100  * bytes.  If the argument of the write operation is also a {@link ByteBuf},
101  * and no source index is specified, the specified buffer's
102  * {@link #readerIndex() readerIndex} is increased together.
103  * <p>
104  * If there's not enough writable bytes left, {@link IndexOutOfBoundsException}
105  * is raised.  The default value of newly allocated buffer's
106  * {@link #writerIndex() writerIndex} is {@code 0}.  The default value of
107  * wrapped or copied buffer's {@link #writerIndex() writerIndex} is the
108  * {@link #capacity() capacity} of the buffer.
109  *
110  * <pre>
111  * // Fills the writable bytes of a buffer with random integers.
112  * {@link ByteBuf} buffer = ...;
113  * while (buffer.maxWritableBytes() >= 4) {
114  *     buffer.writeInt(random.nextInt());
115  * }
116  * </pre>
117  *
118  * <h4>Discardable bytes</h4>
119  *
120  * This segment contains the bytes which were read already by a read operation.
121  * Initially, the size of this segment is {@code 0}, but its size increases up
122  * to the {@link #writerIndex() writerIndex} as read operations are executed.
123  * The read bytes can be discarded by calling {@link #discardReadBytes()} to
124  * reclaim unused area as depicted by the following diagram:
125  *
126  * <pre>
127  *  BEFORE discardReadBytes()
128  *
129  *      +-------------------+------------------+------------------+
130  *      | discardable bytes |  readable bytes  |  writable bytes  |
131  *      +-------------------+------------------+------------------+
132  *      |                   |                  |                  |
133  *      0      <=      readerIndex   <=   writerIndex    <=    capacity
134  *
135  *
136  *  AFTER discardReadBytes()
137  *
138  *      +------------------+--------------------------------------+
139  *      |  readable bytes  |    writable bytes (got more space)   |
140  *      +------------------+--------------------------------------+
141  *      |                  |                                      |
142  * readerIndex (0) <= writerIndex (decreased)        <=        capacity
143  * </pre>
144  *
145  * Please note that there is no guarantee about the content of writable bytes
146  * after calling {@link #discardReadBytes()}.  The writable bytes will not be
147  * moved in most cases and could even be filled with completely different data
148  * depending on the underlying buffer implementation.
149  *
150  * <h4>Clearing the buffer indexes</h4>
151  *
152  * You can set both {@link #readerIndex() readerIndex} and
153  * {@link #writerIndex() writerIndex} to {@code 0} by calling {@link #clear()}.
154  * It does not clear the buffer content (e.g. filling with {@code 0}) but just
155  * clears the two pointers.  Please also note that the semantic of this
156  * operation is different from {@link ByteBuffer#clear()}.
157  *
158  * <pre>
159  *  BEFORE clear()
160  *
161  *      +-------------------+------------------+------------------+
162  *      | discardable bytes |  readable bytes  |  writable bytes  |
163  *      +-------------------+------------------+------------------+
164  *      |                   |                  |                  |
165  *      0      <=      readerIndex   <=   writerIndex    <=    capacity
166  *
167  *
168  *  AFTER clear()
169  *
170  *      +---------------------------------------------------------+
171  *      |             writable bytes (got more space)             |
172  *      +---------------------------------------------------------+
173  *      |                                                         |
174  *      0 = readerIndex = writerIndex            <=            capacity
175  * </pre>
176  *
177  * <h3>Search operations</h3>
178  *
179  * For simple single-byte searches, use {@link #indexOf(int, int, byte)} and {@link #bytesBefore(int, int, byte)}.
180  * {@link #bytesBefore(byte)} is especially useful when you deal with a {@code NUL}-terminated string.
181  * For complicated searches, use {@link #forEachByte(int, int, ByteBufProcessor)} with a {@link ByteBufProcessor}
182  * implementation.
183  *
184  * <h3>Mark and reset</h3>
185  *
186  * There are two marker indexes in every buffer. One is for storing
187  * {@link #readerIndex() readerIndex} and the other is for storing
188  * {@link #writerIndex() writerIndex}.  You can always reposition one of the
189  * two indexes by calling a reset method.  It works in a similar fashion to
190  * the mark and reset methods in {@link InputStream} except that there's no
191  * {@code readlimit}.
192  *
193  * <h3>Derived buffers</h3>
194  *
195  * You can create a view of an existing buffer by calling either
196  * {@link #duplicate()}, {@link #slice()} or {@link #slice(int, int)}.
197  * A derived buffer will have an independent {@link #readerIndex() readerIndex},
198  * {@link #writerIndex() writerIndex} and marker indexes, while it shares
199  * other internal data representation, just like a NIO buffer does.
200  * <p>
201  * In case a completely fresh copy of an existing buffer is required, please
202  * call {@link #copy()} method instead.
203  * <p>
204  * Also be aware that obtaining derived buffers will NOT call {@link #retain()} and so the
205  * reference count will NOT be increased.
206  *
207  * <h3>Conversion to existing JDK types</h3>
208  *
209  * <h4>Byte array</h4>
210  *
211  * If a {@link ByteBuf} is backed by a byte array (i.e. {@code byte[]}),
212  * you can access it directly via the {@link #array()} method.  To determine
213  * if a buffer is backed by a byte array, {@link #hasArray()} should be used.
214  *
215  * <h4>NIO Buffers</h4>
216  *
217  * If a {@link ByteBuf} can be converted into an NIO {@link ByteBuffer} which shares its
218  * content (i.e. view buffer), you can get it via the {@link #nioBuffer()} method.  To determine
219  * if a buffer can be converted into an NIO buffer, use {@link #nioBufferCount()}.
220  *
221  * <h4>Strings</h4>
222  *
223  * Various {@link #toString(Charset)} methods convert a {@link ByteBuf}
224  * into a {@link String}.  Please note that {@link #toString()} is not a
225  * conversion method.
226  *
227  * <h4>I/O Streams</h4>
228  *
229  * Please refer to {@link ByteBufInputStream} and
230  * {@link ByteBufOutputStream}.
231  */
232 @SuppressWarnings("ClassMayBeInterface")
233 public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
234 
235     /**
236      * Returns the number of bytes (octets) this buffer can contain.
237      */
238     public abstract int capacity();
239 
240     /**
241      * Adjusts the capacity of this buffer.  If the {@code newCapacity} is less than the current
242      * capacity, the content of this buffer is truncated.  If the {@code newCapacity} is greater
243      * than the current capacity, the buffer is appended with unspecified data whose length is
244      * {@code (newCapacity - currentCapacity)}.
245      */
246     public abstract ByteBuf capacity(int newCapacity);
247 
248     /**
249      * Returns the maximum allowed capacity of this buffer.  If a user attempts to increase the
250      * capacity of this buffer beyond the maximum capacity using {@link #capacity(int)} or
251      * {@link #ensureWritable(int)}, those methods will raise an
252      * {@link IllegalArgumentException}.
253      */
254     public abstract int maxCapacity();
255 
256     /**
257      * Returns the {@link ByteBufAllocator} which created this buffer.
258      */
259     public abstract ByteBufAllocator alloc();
260 
261     /**
262      * Returns the <a href="http://en.wikipedia.org/wiki/Endianness">endianness</a>
263      * of this buffer.
264      */
265     public abstract ByteOrder order();
266 
267     /**
268      * Returns a buffer with the specified {@code endianness} which shares the whole region,
269      * indexes, and marks of this buffer.  Modifying the content, the indexes, or the marks of the
270      * returned buffer or this buffer affects each other's content, indexes, and marks.  If the
271      * specified {@code endianness} is identical to this buffer's byte order, this method can
272      * return {@code this}.  This method does not modify {@code readerIndex} or {@code writerIndex}
273      * of this buffer.
274      */
275     public abstract ByteBuf order(ByteOrder endianness);
276 
277     /**
278      * Return the underlying buffer instance if this buffer is a wrapper of another buffer.
279      *
280      * @return {@code null} if this buffer is not a wrapper
281      */
282     public abstract ByteBuf unwrap();
283 
284     /**
285      * Returns {@code true} if and only if this buffer is backed by an
286      * NIO direct buffer.
287      */
288     public abstract boolean isDirect();
289 
290     /**
291      * Returns the {@code readerIndex} of this buffer.
292      */
293     public abstract int readerIndex();
294 
295     /**
296      * Sets the {@code readerIndex} of this buffer.
297      *
298      * @throws IndexOutOfBoundsException
299      *         if the specified {@code readerIndex} is
300      *            less than {@code 0} or
301      *            greater than {@code this.writerIndex}
302      */
303     public abstract ByteBuf readerIndex(int readerIndex);
304 
305     /**
306      * Returns the {@code writerIndex} of this buffer.
307      */
308     public abstract int writerIndex();
309 
310     /**
311      * Sets the {@code writerIndex} of this buffer.
312      *
313      * @throws IndexOutOfBoundsException
314      *         if the specified {@code writerIndex} is
315      *            less than {@code this.readerIndex} or
316      *            greater than {@code this.capacity}
317      */
318     public abstract ByteBuf writerIndex(int writerIndex);
319 
320     /**
321      * Sets the {@code readerIndex} and {@code writerIndex} of this buffer
322      * in one shot.  This method is useful when you have to worry about the
323      * invocation order of {@link #readerIndex(int)} and {@link #writerIndex(int)}
324      * methods.  For example, the following code will fail:
325      *
326      * <pre>
327      * // Create a buffer whose readerIndex, writerIndex and capacity are
328      * // 0, 0 and 8 respectively.
329      * {@link ByteBuf} buf = {@link Unpooled}.buffer(8);
330      *
331      * // IndexOutOfBoundsException is thrown because the specified
332      * // readerIndex (2) cannot be greater than the current writerIndex (0).
333      * buf.readerIndex(2);
334      * buf.writerIndex(4);
335      * </pre>
336      *
337      * The following code will also fail:
338      *
339      * <pre>
340      * // Create a buffer whose readerIndex, writerIndex and capacity are
341      * // 0, 8 and 8 respectively.
342      * {@link ByteBuf} buf = {@link Unpooled}.wrappedBuffer(new byte[8]);
343      *
344      * // readerIndex becomes 8.
345      * buf.readLong();
346      *
347      * // IndexOutOfBoundsException is thrown because the specified
348      * // writerIndex (4) cannot be less than the current readerIndex (8).
349      * buf.writerIndex(4);
350      * buf.readerIndex(2);
351      * </pre>
352      *
353      * By contrast, this method guarantees that it never
354      * throws an {@link IndexOutOfBoundsException} as long as the specified
355      * indexes meet basic constraints, regardless what the current index
356      * values of the buffer are:
357      *
358      * <pre>
359      * // No matter what the current state of the buffer is, the following
360      * // call always succeeds as long as the capacity of the buffer is not
361      * // less than 4.
362      * buf.setIndex(2, 4);
363      * </pre>
364      *
365      * @throws IndexOutOfBoundsException
366      *         if the specified {@code readerIndex} is less than 0,
367      *         if the specified {@code writerIndex} is less than the specified
368      *         {@code readerIndex} or if the specified {@code writerIndex} is
369      *         greater than {@code this.capacity}
370      */
371     public abstract ByteBuf setIndex(int readerIndex, int writerIndex);
372 
373     /**
374      * Returns the number of readable bytes which is equal to
375      * {@code (this.writerIndex - this.readerIndex)}.
376      */
377     public abstract int readableBytes();
378 
379     /**
380      * Returns the number of writable bytes which is equal to
381      * {@code (this.capacity - this.writerIndex)}.
382      */
383     public abstract int writableBytes();
384 
385     /**
386      * Returns the maximum possible number of writable bytes, which is equal to
387      * {@code (this.maxCapacity - this.writerIndex)}.
388      */
389     public abstract int maxWritableBytes();
390 
391     /**
392      * Returns {@code true}
393      * if and only if {@code (this.writerIndex - this.readerIndex)} is greater
394      * than {@code 0}.
395      */
396     public abstract boolean isReadable();
397 
398     /**
399      * Returns {@code true} if and only if this buffer contains equal to or more than the specified number of elements.
400      */
401     public abstract boolean isReadable(int size);
402 
403     /**
404      * Returns {@code true}
405      * if and only if {@code (this.capacity - this.writerIndex)} is greater
406      * than {@code 0}.
407      */
408     public abstract boolean isWritable();
409 
410     /**
411      * Returns {@code true} if and only if this buffer has enough room to allow writing the specified number of
412      * elements.
413      */
414     public abstract boolean isWritable(int size);
415 
416     /**
417      * Sets the {@code readerIndex} and {@code writerIndex} of this buffer to
418      * {@code 0}.
419      * This method is identical to {@link #setIndex(int, int) setIndex(0, 0)}.
420      * <p>
421      * Please note that the behavior of this method is different
422      * from that of NIO buffer, which sets the {@code limit} to
423      * the {@code capacity} of the buffer.
424      */
425     public abstract ByteBuf clear();
426 
427     /**
428      * Marks the current {@code readerIndex} in this buffer.  You can
429      * reposition the current {@code readerIndex} to the marked
430      * {@code readerIndex} by calling {@link #resetReaderIndex()}.
431      * The initial value of the marked {@code readerIndex} is {@code 0}.
432      */
433     public abstract ByteBuf markReaderIndex();
434 
435     /**
436      * Repositions the current {@code readerIndex} to the marked
437      * {@code readerIndex} in this buffer.
438      *
439      * @throws IndexOutOfBoundsException
440      *         if the current {@code writerIndex} is less than the marked
441      *         {@code readerIndex}
442      */
443     public abstract ByteBuf resetReaderIndex();
444 
445     /**
446      * Marks the current {@code writerIndex} in this buffer.  You can
447      * reposition the current {@code writerIndex} to the marked
448      * {@code writerIndex} by calling {@link #resetWriterIndex()}.
449      * The initial value of the marked {@code writerIndex} is {@code 0}.
450      */
451     public abstract ByteBuf markWriterIndex();
452 
453     /**
454      * Repositions the current {@code writerIndex} to the marked
455      * {@code writerIndex} in this buffer.
456      *
457      * @throws IndexOutOfBoundsException
458      *         if the current {@code readerIndex} is greater than the marked
459      *         {@code writerIndex}
460      */
461     public abstract ByteBuf resetWriterIndex();
462 
463     /**
464      * Discards the bytes between the 0th index and {@code readerIndex}.
465      * It moves the bytes between {@code readerIndex} and {@code writerIndex}
466      * to the 0th index, and sets {@code readerIndex} and {@code writerIndex}
467      * to {@code 0} and {@code oldWriterIndex - oldReaderIndex} respectively.
468      * <p>
469      * Please refer to the class documentation for more detailed explanation.
470      */
471     public abstract ByteBuf discardReadBytes();
472 
473     /**
474      * Similar to {@link ByteBuf#discardReadBytes()} except that this method might discard
475      * some, all, or none of read bytes depending on its internal implementation to reduce
476      * overall memory bandwidth consumption at the cost of potentially additional memory
477      * consumption.
478      */
479     public abstract ByteBuf discardSomeReadBytes();
480 
481     /**
482      * Makes sure the number of {@linkplain #writableBytes() the writable bytes}
483      * is equal to or greater than the specified value.  If there is enough
484      * writable bytes in this buffer, this method returns with no side effect.
485      * Otherwise, it raises an {@link IllegalArgumentException}.
486      *
487      * @param minWritableBytes
488      *        the expected minimum number of writable bytes
489      * @throws IndexOutOfBoundsException
490      *         if {@link #writerIndex()} + {@code minWritableBytes} > {@link #maxCapacity()}
491      */
492     public abstract ByteBuf ensureWritable(int minWritableBytes);
493 
494     /**
495      * Tries to make sure the number of {@linkplain #writableBytes() the writable bytes}
496      * is equal to or greater than the specified value.  Unlike {@link #ensureWritable(int)},
497      * this method does not raise an exception but returns a code.
498      *
499      * @param minWritableBytes
500      *        the expected minimum number of writable bytes
501      * @param force
502      *        When {@link #writerIndex()} + {@code minWritableBytes} > {@link #maxCapacity()}:
503      *        <ul>
504      *        <li>{@code true} - the capacity of the buffer is expanded to {@link #maxCapacity()}</li>
505      *        <li>{@code false} - the capacity of the buffer is unchanged</li>
506      *        </ul>
507      * @return {@code 0} if the buffer has enough writable bytes, and its capacity is unchanged.
508      *         {@code 1} if the buffer does not have enough bytes, and its capacity is unchanged.
509      *         {@code 2} if the buffer has enough writable bytes, and its capacity has been increased.
510      *         {@code 3} if the buffer does not have enough bytes, but its capacity has been
511      *                   increased to its maximum.
512      */
513     public abstract int ensureWritable(int minWritableBytes, boolean force);
514 
515     /**
516      * Gets a boolean at the specified absolute (@code index) in this buffer.
517      * This method does not modify the {@code readerIndex} or {@code writerIndex}
518      * of this buffer.
519      *
520      * @throws IndexOutOfBoundsException
521      *         if the specified {@code index} is less than {@code 0} or
522      *         {@code index + 1} is greater than {@code this.capacity}
523      */
524     public abstract boolean getBoolean(int index);
525 
526     /**
527      * Gets a byte at the specified absolute {@code index} in this buffer.
528      * This method does not modify {@code readerIndex} or {@code writerIndex} of
529      * this buffer.
530      *
531      * @throws IndexOutOfBoundsException
532      *         if the specified {@code index} is less than {@code 0} or
533      *         {@code index + 1} is greater than {@code this.capacity}
534      */
535     public abstract byte  getByte(int index);
536 
537     /**
538      * Gets an unsigned byte at the specified absolute {@code index} in this
539      * buffer.  This method does not modify {@code readerIndex} or
540      * {@code writerIndex} of this buffer.
541      *
542      * @throws IndexOutOfBoundsException
543      *         if the specified {@code index} is less than {@code 0} or
544      *         {@code index + 1} is greater than {@code this.capacity}
545      */
546     public abstract short getUnsignedByte(int index);
547 
548     /**
549      * Gets a 16-bit short integer at the specified absolute {@code index} in
550      * this buffer.  This method does not modify {@code readerIndex} or
551      * {@code writerIndex} of this buffer.
552      *
553      * @throws IndexOutOfBoundsException
554      *         if the specified {@code index} is less than {@code 0} or
555      *         {@code index + 2} is greater than {@code this.capacity}
556      */
557     public abstract short getShort(int index);
558 
559     /**
560      * Gets an unsigned 16-bit short integer at the specified absolute
561      * {@code index} in this buffer.  This method does not modify
562      * {@code readerIndex} or {@code writerIndex} of this buffer.
563      *
564      * @throws IndexOutOfBoundsException
565      *         if the specified {@code index} is less than {@code 0} or
566      *         {@code index + 2} is greater than {@code this.capacity}
567      */
568     public abstract int getUnsignedShort(int index);
569 
570     /**
571      * Gets a 24-bit medium integer at the specified absolute {@code index} in
572      * this buffer.  This method does not modify {@code readerIndex} or
573      * {@code writerIndex} of this buffer.
574      *
575      * @throws IndexOutOfBoundsException
576      *         if the specified {@code index} is less than {@code 0} or
577      *         {@code index + 3} is greater than {@code this.capacity}
578      */
579     public abstract int   getMedium(int index);
580 
581     /**
582      * Gets an unsigned 24-bit medium integer at the specified absolute
583      * {@code index} in this buffer.  This method does not modify
584      * {@code readerIndex} or {@code writerIndex} of this buffer.
585      *
586      * @throws IndexOutOfBoundsException
587      *         if the specified {@code index} is less than {@code 0} or
588      *         {@code index + 3} is greater than {@code this.capacity}
589      */
590     public abstract int   getUnsignedMedium(int index);
591 
592     /**
593      * Gets a 32-bit integer at the specified absolute {@code index} in
594      * this buffer.  This method does not modify {@code readerIndex} or
595      * {@code writerIndex} of this buffer.
596      *
597      * @throws IndexOutOfBoundsException
598      *         if the specified {@code index} is less than {@code 0} or
599      *         {@code index + 4} is greater than {@code this.capacity}
600      */
601     public abstract int   getInt(int index);
602 
603     /**
604      * Gets an unsigned 32-bit integer at the specified absolute {@code index}
605      * in this buffer.  This method does not modify {@code readerIndex} or
606      * {@code writerIndex} of this buffer.
607      *
608      * @throws IndexOutOfBoundsException
609      *         if the specified {@code index} is less than {@code 0} or
610      *         {@code index + 4} is greater than {@code this.capacity}
611      */
612     public abstract long  getUnsignedInt(int index);
613 
614     /**
615      * Gets a 64-bit long integer at the specified absolute {@code index} in
616      * this buffer.  This method does not modify {@code readerIndex} or
617      * {@code writerIndex} of this buffer.
618      *
619      * @throws IndexOutOfBoundsException
620      *         if the specified {@code index} is less than {@code 0} or
621      *         {@code index + 8} is greater than {@code this.capacity}
622      */
623     public abstract long  getLong(int index);
624 
625     /**
626      * Gets a 2-byte UTF-16 character at the specified absolute
627      * {@code index} in this buffer.  This method does not modify
628      * {@code readerIndex} or {@code writerIndex} of this buffer.
629      *
630      * @throws IndexOutOfBoundsException
631      *         if the specified {@code index} is less than {@code 0} or
632      *         {@code index + 2} is greater than {@code this.capacity}
633      */
634     public abstract char  getChar(int index);
635 
636     /**
637      * Gets a 32-bit floating point number at the specified absolute
638      * {@code index} in this buffer.  This method does not modify
639      * {@code readerIndex} or {@code writerIndex} of this buffer.
640      *
641      * @throws IndexOutOfBoundsException
642      *         if the specified {@code index} is less than {@code 0} or
643      *         {@code index + 4} is greater than {@code this.capacity}
644      */
645     public abstract float getFloat(int index);
646 
647     /**
648      * Gets a 64-bit floating point number at the specified absolute
649      * {@code index} in this buffer.  This method does not modify
650      * {@code readerIndex} or {@code writerIndex} of this buffer.
651      *
652      * @throws IndexOutOfBoundsException
653      *         if the specified {@code index} is less than {@code 0} or
654      *         {@code index + 8} is greater than {@code this.capacity}
655      */
656     public abstract double getDouble(int index);
657 
658     /**
659      * Transfers this buffer's data to the specified destination starting at
660      * the specified absolute {@code index} until the destination becomes
661      * non-writable.  This method is basically same with
662      * {@link #getBytes(int, ByteBuf, int, int)}, except that this
663      * method increases the {@code writerIndex} of the destination by the
664      * number of the transferred bytes while
665      * {@link #getBytes(int, ByteBuf, int, int)} does not.
666      * This method does not modify {@code readerIndex} or {@code writerIndex} of
667      * the source buffer (i.e. {@code this}).
668      *
669      * @throws IndexOutOfBoundsException
670      *         if the specified {@code index} is less than {@code 0} or
671      *         if {@code index + dst.writableBytes} is greater than
672      *            {@code this.capacity}
673      */
674     public abstract ByteBuf getBytes(int index, ByteBuf dst);
675 
676     /**
677      * Transfers this buffer's data to the specified destination starting at
678      * the specified absolute {@code index}.  This method is basically same
679      * with {@link #getBytes(int, ByteBuf, int, int)}, except that this
680      * method increases the {@code writerIndex} of the destination by the
681      * number of the transferred bytes while
682      * {@link #getBytes(int, ByteBuf, int, int)} does not.
683      * This method does not modify {@code readerIndex} or {@code writerIndex} of
684      * the source buffer (i.e. {@code this}).
685      *
686      * @param length the number of bytes to transfer
687      *
688      * @throws IndexOutOfBoundsException
689      *         if the specified {@code index} is less than {@code 0},
690      *         if {@code index + length} is greater than
691      *            {@code this.capacity}, or
692      *         if {@code length} is greater than {@code dst.writableBytes}
693      */
694     public abstract ByteBuf getBytes(int index, ByteBuf dst, int length);
695 
696     /**
697      * Transfers this buffer's data to the specified destination starting at
698      * the specified absolute {@code index}.
699      * This method does not modify {@code readerIndex} or {@code writerIndex}
700      * of both the source (i.e. {@code this}) and the destination.
701      *
702      * @param dstIndex the first index of the destination
703      * @param length   the number of bytes to transfer
704      *
705      * @throws IndexOutOfBoundsException
706      *         if the specified {@code index} is less than {@code 0},
707      *         if the specified {@code dstIndex} is less than {@code 0},
708      *         if {@code index + length} is greater than
709      *            {@code this.capacity}, or
710      *         if {@code dstIndex + length} is greater than
711      *            {@code dst.capacity}
712      */
713     public abstract ByteBuf getBytes(int index, ByteBuf dst, int dstIndex, int length);
714 
715     /**
716      * Transfers this buffer's data to the specified destination starting at
717      * the specified absolute {@code index}.
718      * This method does not modify {@code readerIndex} or {@code writerIndex} of
719      * this buffer
720      *
721      * @throws IndexOutOfBoundsException
722      *         if the specified {@code index} is less than {@code 0} or
723      *         if {@code index + dst.length} is greater than
724      *            {@code this.capacity}
725      */
726     public abstract ByteBuf getBytes(int index, byte[] dst);
727 
728     /**
729      * Transfers this buffer's data to the specified destination starting at
730      * the specified absolute {@code index}.
731      * This method does not modify {@code readerIndex} or {@code writerIndex}
732      * of this buffer.
733      *
734      * @param dstIndex the first index of the destination
735      * @param length   the number of bytes to transfer
736      *
737      * @throws IndexOutOfBoundsException
738      *         if the specified {@code index} is less than {@code 0},
739      *         if the specified {@code dstIndex} is less than {@code 0},
740      *         if {@code index + length} is greater than
741      *            {@code this.capacity}, or
742      *         if {@code dstIndex + length} is greater than
743      *            {@code dst.length}
744      */
745     public abstract ByteBuf getBytes(int index, byte[] dst, int dstIndex, int length);
746 
747     /**
748      * Transfers this buffer's data to the specified destination starting at
749      * the specified absolute {@code index} until the destination's position
750      * reaches its limit.
751      * This method does not modify {@code readerIndex} or {@code writerIndex} of
752      * this buffer while the destination's {@code position} will be increased.
753      *
754      * @throws IndexOutOfBoundsException
755      *         if the specified {@code index} is less than {@code 0} or
756      *         if {@code index + dst.remaining()} is greater than
757      *            {@code this.capacity}
758      */
759     public abstract ByteBuf getBytes(int index, ByteBuffer dst);
760 
761     /**
762      * Transfers this buffer's data to the specified stream starting at the
763      * specified absolute {@code index}.
764      * This method does not modify {@code readerIndex} or {@code writerIndex} of
765      * this buffer.
766      *
767      * @param length the number of bytes to transfer
768      *
769      * @throws IndexOutOfBoundsException
770      *         if the specified {@code index} is less than {@code 0} or
771      *         if {@code index + length} is greater than
772      *            {@code this.capacity}
773      * @throws IOException
774      *         if the specified stream threw an exception during I/O
775      */
776     public abstract ByteBuf getBytes(int index, OutputStream out, int length) throws IOException;
777 
778     /**
779      * Transfers this buffer's data to the specified channel starting at the
780      * specified absolute {@code index}.
781      * This method does not modify {@code readerIndex} or {@code writerIndex} of
782      * this buffer.
783      *
784      * @param length the maximum number of bytes to transfer
785      *
786      * @return the actual number of bytes written out to the specified channel
787      *
788      * @throws IndexOutOfBoundsException
789      *         if the specified {@code index} is less than {@code 0} or
790      *         if {@code index + length} is greater than
791      *            {@code this.capacity}
792      * @throws IOException
793      *         if the specified channel threw an exception during I/O
794      */
795     public abstract int getBytes(int index, GatheringByteChannel out, int length) throws IOException;
796 
797     /**
798      * Sets the specified boolean at the specified absolute {@code index} in this
799      * buffer.
800      * This method does not modify {@code readerIndex} or {@code writerIndex} of
801      * this buffer.
802      *
803      * @throws IndexOutOfBoundsException
804      *         if the specified {@code index} is less than {@code 0} or
805      *         {@code index + 1} is greater than {@code this.capacity}
806      */
807     public abstract ByteBuf setBoolean(int index, boolean value);
808 
809     /**
810      * Sets the specified byte at the specified absolute {@code index} in this
811      * buffer.  The 24 high-order bits of the specified value are ignored.
812      * This method does not modify {@code readerIndex} or {@code writerIndex} of
813      * this buffer.
814      *
815      * @throws IndexOutOfBoundsException
816      *         if the specified {@code index} is less than {@code 0} or
817      *         {@code index + 1} is greater than {@code this.capacity}
818      */
819     public abstract ByteBuf setByte(int index, int value);
820 
821     /**
822      * Sets the specified 16-bit short integer at the specified absolute
823      * {@code index} in this buffer.  The 16 high-order bits of the specified
824      * value are ignored.
825      * This method does not modify {@code readerIndex} or {@code writerIndex} of
826      * this buffer.
827      *
828      * @throws IndexOutOfBoundsException
829      *         if the specified {@code index} is less than {@code 0} or
830      *         {@code index + 2} is greater than {@code this.capacity}
831      */
832     public abstract ByteBuf setShort(int index, int value);
833 
834     /**
835      * Sets the specified 24-bit medium integer at the specified absolute
836      * {@code index} in this buffer.  Please note that the most significant
837      * byte is ignored in the specified value.
838      * This method does not modify {@code readerIndex} or {@code writerIndex} of
839      * this buffer.
840      *
841      * @throws IndexOutOfBoundsException
842      *         if the specified {@code index} is less than {@code 0} or
843      *         {@code index + 3} is greater than {@code this.capacity}
844      */
845     public abstract ByteBuf setMedium(int index, int value);
846 
847     /**
848      * Sets the specified 32-bit integer at the specified absolute
849      * {@code index} in this buffer.
850      * This method does not modify {@code readerIndex} or {@code writerIndex} of
851      * this buffer.
852      *
853      * @throws IndexOutOfBoundsException
854      *         if the specified {@code index} is less than {@code 0} or
855      *         {@code index + 4} is greater than {@code this.capacity}
856      */
857     public abstract ByteBuf setInt(int index, int value);
858 
859     /**
860      * Sets the specified 64-bit long integer at the specified absolute
861      * {@code index} in this buffer.
862      * This method does not modify {@code readerIndex} or {@code writerIndex} of
863      * this buffer.
864      *
865      * @throws IndexOutOfBoundsException
866      *         if the specified {@code index} is less than {@code 0} or
867      *         {@code index + 8} is greater than {@code this.capacity}
868      */
869     public abstract ByteBuf setLong(int index, long value);
870 
871     /**
872      * Sets the specified 2-byte UTF-16 character at the specified absolute
873      * {@code index} in this buffer.
874      * The 16 high-order bits of the specified value are ignored.
875      * This method does not modify {@code readerIndex} or {@code writerIndex} of
876      * this buffer.
877      *
878      * @throws IndexOutOfBoundsException
879      *         if the specified {@code index} is less than {@code 0} or
880      *         {@code index + 2} is greater than {@code this.capacity}
881      */
882     public abstract ByteBuf setChar(int index, int value);
883 
884     /**
885      * Sets the specified 32-bit floating-point number at the specified
886      * absolute {@code index} in this buffer.
887      * This method does not modify {@code readerIndex} or {@code writerIndex} of
888      * this buffer.
889      *
890      * @throws IndexOutOfBoundsException
891      *         if the specified {@code index} is less than {@code 0} or
892      *         {@code index + 4} is greater than {@code this.capacity}
893      */
894     public abstract ByteBuf setFloat(int index, float value);
895 
896     /**
897      * Sets the specified 64-bit floating-point number at the specified
898      * absolute {@code index} in this buffer.
899      * This method does not modify {@code readerIndex} or {@code writerIndex} of
900      * this buffer.
901      *
902      * @throws IndexOutOfBoundsException
903      *         if the specified {@code index} is less than {@code 0} or
904      *         {@code index + 8} is greater than {@code this.capacity}
905      */
906     public abstract ByteBuf setDouble(int index, double value);
907 
908     /**
909      * Transfers the specified source buffer's data to this buffer starting at
910      * the specified absolute {@code index} until the source buffer becomes
911      * unreadable.  This method is basically same with
912      * {@link #setBytes(int, ByteBuf, int, int)}, except that this
913      * method increases the {@code readerIndex} of the source buffer by
914      * the number of the transferred bytes while
915      * {@link #setBytes(int, ByteBuf, int, int)} does not.
916      * This method does not modify {@code readerIndex} or {@code writerIndex} of
917      * the source buffer (i.e. {@code this}).
918      *
919      * @throws IndexOutOfBoundsException
920      *         if the specified {@code index} is less than {@code 0} or
921      *         if {@code index + src.readableBytes} is greater than
922      *            {@code this.capacity}
923      */
924     public abstract ByteBuf setBytes(int index, ByteBuf src);
925 
926     /**
927      * Transfers the specified source buffer's data to this buffer starting at
928      * the specified absolute {@code index}.  This method is basically same
929      * with {@link #setBytes(int, ByteBuf, int, int)}, except that this
930      * method increases the {@code readerIndex} of the source buffer by
931      * the number of the transferred bytes while
932      * {@link #setBytes(int, ByteBuf, int, int)} does not.
933      * This method does not modify {@code readerIndex} or {@code writerIndex} of
934      * the source buffer (i.e. {@code this}).
935      *
936      * @param length the number of bytes to transfer
937      *
938      * @throws IndexOutOfBoundsException
939      *         if the specified {@code index} is less than {@code 0},
940      *         if {@code index + length} is greater than
941      *            {@code this.capacity}, or
942      *         if {@code length} is greater than {@code src.readableBytes}
943      */
944     public abstract ByteBuf setBytes(int index, ByteBuf src, int length);
945 
946     /**
947      * Transfers the specified source buffer's data to this buffer starting at
948      * the specified absolute {@code index}.
949      * This method does not modify {@code readerIndex} or {@code writerIndex}
950      * of both the source (i.e. {@code this}) and the destination.
951      *
952      * @param srcIndex the first index of the source
953      * @param length   the number of bytes to transfer
954      *
955      * @throws IndexOutOfBoundsException
956      *         if the specified {@code index} is less than {@code 0},
957      *         if the specified {@code srcIndex} is less than {@code 0},
958      *         if {@code index + length} is greater than
959      *            {@code this.capacity}, or
960      *         if {@code srcIndex + length} is greater than
961      *            {@code src.capacity}
962      */
963     public abstract ByteBuf setBytes(int index, ByteBuf src, int srcIndex, int length);
964 
965     /**
966      * Transfers the specified source array's data to this buffer starting at
967      * the specified absolute {@code index}.
968      * This method does not modify {@code readerIndex} or {@code writerIndex} of
969      * this buffer.
970      *
971      * @throws IndexOutOfBoundsException
972      *         if the specified {@code index} is less than {@code 0} or
973      *         if {@code index + src.length} is greater than
974      *            {@code this.capacity}
975      */
976     public abstract ByteBuf setBytes(int index, byte[] src);
977 
978     /**
979      * Transfers the specified source array's data to this buffer starting at
980      * the specified absolute {@code index}.
981      * This method does not modify {@code readerIndex} or {@code writerIndex} of
982      * this buffer.
983      *
984      * @throws IndexOutOfBoundsException
985      *         if the specified {@code index} is less than {@code 0},
986      *         if the specified {@code srcIndex} is less than {@code 0},
987      *         if {@code index + length} is greater than
988      *            {@code this.capacity}, or
989      *         if {@code srcIndex + length} is greater than {@code src.length}
990      */
991     public abstract ByteBuf setBytes(int index, byte[] src, int srcIndex, int length);
992 
993     /**
994      * Transfers the specified source buffer's data to this buffer starting at
995      * the specified absolute {@code index} until the source buffer's position
996      * reaches its limit.
997      * This method does not modify {@code readerIndex} or {@code writerIndex} of
998      * this buffer.
999      *
1000      * @throws IndexOutOfBoundsException
1001      *         if the specified {@code index} is less than {@code 0} or
1002      *         if {@code index + src.remaining()} is greater than
1003      *            {@code this.capacity}
1004      */
1005     public abstract ByteBuf setBytes(int index, ByteBuffer src);
1006 
1007     /**
1008      * Transfers the content of the specified source stream to this buffer
1009      * starting at the specified absolute {@code index}.
1010      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1011      * this buffer.
1012      *
1013      * @param length the number of bytes to transfer
1014      *
1015      * @return the actual number of bytes read in from the specified channel.
1016      *         {@code -1} if the specified channel is closed.
1017      *
1018      * @throws IndexOutOfBoundsException
1019      *         if the specified {@code index} is less than {@code 0} or
1020      *         if {@code index + length} is greater than {@code this.capacity}
1021      * @throws IOException
1022      *         if the specified stream threw an exception during I/O
1023      */
1024     public abstract int setBytes(int index, InputStream in, int length) throws IOException;
1025 
1026     /**
1027      * Transfers the content of the specified source channel to this buffer
1028      * starting at the specified absolute {@code index}.
1029      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1030      * this buffer.
1031      *
1032      * @param length the maximum number of bytes to transfer
1033      *
1034      * @return the actual number of bytes read in from the specified channel.
1035      *         {@code -1} if the specified channel is closed.
1036      *
1037      * @throws IndexOutOfBoundsException
1038      *         if the specified {@code index} is less than {@code 0} or
1039      *         if {@code index + length} is greater than {@code this.capacity}
1040      * @throws IOException
1041      *         if the specified channel threw an exception during I/O
1042      */
1043     public abstract int  setBytes(int index, ScatteringByteChannel in, int length) throws IOException;
1044 
1045     /**
1046      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the specified
1047      * absolute {@code index}.
1048      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1049      * this buffer.
1050      *
1051      * @param length the number of <tt>NUL</tt>s to write to the buffer
1052      *
1053      * @throws IndexOutOfBoundsException
1054      *         if the specified {@code index} is less than {@code 0} or
1055      *         if {@code index + length} is greater than {@code this.capacity}
1056      */
1057     public abstract ByteBuf setZero(int index, int length);
1058 
1059     /**
1060      * Gets a boolean at the current {@code readerIndex} and increases
1061      * the {@code readerIndex} by {@code 1} in this buffer.
1062      *
1063      * @throws IndexOutOfBoundsException
1064      *         if {@code this.readableBytes} is less than {@code 1}
1065      */
1066     public abstract boolean readBoolean();
1067 
1068     /**
1069      * Gets a byte at the current {@code readerIndex} and increases
1070      * the {@code readerIndex} by {@code 1} in this buffer.
1071      *
1072      * @throws IndexOutOfBoundsException
1073      *         if {@code this.readableBytes} is less than {@code 1}
1074      */
1075     public abstract byte  readByte();
1076 
1077     /**
1078      * Gets an unsigned byte at the current {@code readerIndex} and increases
1079      * the {@code readerIndex} by {@code 1} in this buffer.
1080      *
1081      * @throws IndexOutOfBoundsException
1082      *         if {@code this.readableBytes} is less than {@code 1}
1083      */
1084     public abstract short readUnsignedByte();
1085 
1086     /**
1087      * Gets a 16-bit short integer at the current {@code readerIndex}
1088      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1089      *
1090      * @throws IndexOutOfBoundsException
1091      *         if {@code this.readableBytes} is less than {@code 2}
1092      */
1093     public abstract short readShort();
1094 
1095     /**
1096      * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1097      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1098      *
1099      * @throws IndexOutOfBoundsException
1100      *         if {@code this.readableBytes} is less than {@code 2}
1101      */
1102     public abstract int   readUnsignedShort();
1103 
1104     /**
1105      * Gets a 24-bit medium integer at the current {@code readerIndex}
1106      * and increases the {@code readerIndex} by {@code 3} in this buffer.
1107      *
1108      * @throws IndexOutOfBoundsException
1109      *         if {@code this.readableBytes} is less than {@code 3}
1110      */
1111     public abstract int   readMedium();
1112 
1113     /**
1114      * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1115      * and increases the {@code readerIndex} by {@code 3} in this buffer.
1116      *
1117      * @throws IndexOutOfBoundsException
1118      *         if {@code this.readableBytes} is less than {@code 3}
1119      */
1120     public abstract int   readUnsignedMedium();
1121 
1122     /**
1123      * Gets a 32-bit integer at the current {@code readerIndex}
1124      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1125      *
1126      * @throws IndexOutOfBoundsException
1127      *         if {@code this.readableBytes} is less than {@code 4}
1128      */
1129     public abstract int   readInt();
1130 
1131     /**
1132      * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1133      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1134      *
1135      * @throws IndexOutOfBoundsException
1136      *         if {@code this.readableBytes} is less than {@code 4}
1137      */
1138     public abstract long  readUnsignedInt();
1139 
1140     /**
1141      * Gets a 64-bit integer at the current {@code readerIndex}
1142      * and increases the {@code readerIndex} by {@code 8} in this buffer.
1143      *
1144      * @throws IndexOutOfBoundsException
1145      *         if {@code this.readableBytes} is less than {@code 8}
1146      */
1147     public abstract long  readLong();
1148 
1149     /**
1150      * Gets a 2-byte UTF-16 character at the current {@code readerIndex}
1151      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1152      *
1153      * @throws IndexOutOfBoundsException
1154      *         if {@code this.readableBytes} is less than {@code 2}
1155      */
1156     public abstract char  readChar();
1157 
1158     /**
1159      * Gets a 32-bit floating point number at the current {@code readerIndex}
1160      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1161      *
1162      * @throws IndexOutOfBoundsException
1163      *         if {@code this.readableBytes} is less than {@code 4}
1164      */
1165     public abstract float readFloat();
1166 
1167     /**
1168      * Gets a 64-bit floating point number at the current {@code readerIndex}
1169      * and increases the {@code readerIndex} by {@code 8} in this buffer.
1170      *
1171      * @throws IndexOutOfBoundsException
1172      *         if {@code this.readableBytes} is less than {@code 8}
1173      */
1174     public abstract double readDouble();
1175 
1176     /**
1177      * Transfers this buffer's data to a newly created buffer starting at
1178      * the current {@code readerIndex} and increases the {@code readerIndex}
1179      * by the number of the transferred bytes (= {@code length}).
1180      * The returned buffer's {@code readerIndex} and {@code writerIndex} are
1181      * {@code 0} and {@code length} respectively.
1182      *
1183      * @param length the number of bytes to transfer
1184      *
1185      * @return the newly created buffer which contains the transferred bytes
1186      *
1187      * @throws IndexOutOfBoundsException
1188      *         if {@code length} is greater than {@code this.readableBytes}
1189      */
1190     public abstract ByteBuf readBytes(int length);
1191 
1192     /**
1193      * Returns a new slice of this buffer's sub-region starting at the current
1194      * {@code readerIndex} and increases the {@code readerIndex} by the size
1195      * of the new slice (= {@code length}).
1196      * <p>
1197      * Also be aware that this method will NOT call {@link #retain()} and so the
1198      * reference count will NOT be increased.
1199      *
1200      * @param length the size of the new slice
1201      *
1202      * @return the newly created slice
1203      *
1204      * @throws IndexOutOfBoundsException
1205      *         if {@code length} is greater than {@code this.readableBytes}
1206      */
1207     public abstract ByteBuf readSlice(int length);
1208 
1209     /**
1210      * Transfers this buffer's data to the specified destination starting at
1211      * the current {@code readerIndex} until the destination becomes
1212      * non-writable, and increases the {@code readerIndex} by the number of the
1213      * transferred bytes.  This method is basically same with
1214      * {@link #readBytes(ByteBuf, int, int)}, except that this method
1215      * increases the {@code writerIndex} of the destination by the number of
1216      * the transferred bytes while {@link #readBytes(ByteBuf, int, int)}
1217      * does not.
1218      *
1219      * @throws IndexOutOfBoundsException
1220      *         if {@code dst.writableBytes} is greater than
1221      *            {@code this.readableBytes}
1222      */
1223     public abstract ByteBuf readBytes(ByteBuf dst);
1224 
1225     /**
1226      * Transfers this buffer's data to the specified destination starting at
1227      * the current {@code readerIndex} and increases the {@code readerIndex}
1228      * by the number of the transferred bytes (= {@code length}).  This method
1229      * is basically same with {@link #readBytes(ByteBuf, int, int)},
1230      * except that this method increases the {@code writerIndex} of the
1231      * destination by the number of the transferred bytes (= {@code length})
1232      * while {@link #readBytes(ByteBuf, int, int)} does not.
1233      *
1234      * @throws IndexOutOfBoundsException
1235      *         if {@code length} is greater than {@code this.readableBytes} or
1236      *         if {@code length} is greater than {@code dst.writableBytes}
1237      */
1238     public abstract ByteBuf readBytes(ByteBuf dst, int length);
1239 
1240     /**
1241      * Transfers this buffer's data to the specified destination starting at
1242      * the current {@code readerIndex} and increases the {@code readerIndex}
1243      * by the number of the transferred bytes (= {@code length}).
1244      *
1245      * @param dstIndex the first index of the destination
1246      * @param length   the number of bytes to transfer
1247      *
1248      * @throws IndexOutOfBoundsException
1249      *         if the specified {@code dstIndex} is less than {@code 0},
1250      *         if {@code length} is greater than {@code this.readableBytes}, or
1251      *         if {@code dstIndex + length} is greater than
1252      *            {@code dst.capacity}
1253      */
1254     public abstract ByteBuf readBytes(ByteBuf dst, int dstIndex, int length);
1255 
1256     /**
1257      * Transfers this buffer's data to the specified destination starting at
1258      * the current {@code readerIndex} and increases the {@code readerIndex}
1259      * by the number of the transferred bytes (= {@code dst.length}).
1260      *
1261      * @throws IndexOutOfBoundsException
1262      *         if {@code dst.length} is greater than {@code this.readableBytes}
1263      */
1264     public abstract ByteBuf readBytes(byte[] dst);
1265 
1266     /**
1267      * Transfers this buffer's data to the specified destination starting at
1268      * the current {@code readerIndex} and increases the {@code readerIndex}
1269      * by the number of the transferred bytes (= {@code length}).
1270      *
1271      * @param dstIndex the first index of the destination
1272      * @param length   the number of bytes to transfer
1273      *
1274      * @throws IndexOutOfBoundsException
1275      *         if the specified {@code dstIndex} is less than {@code 0},
1276      *         if {@code length} is greater than {@code this.readableBytes}, or
1277      *         if {@code dstIndex + length} is greater than {@code dst.length}
1278      */
1279     public abstract ByteBuf readBytes(byte[] dst, int dstIndex, int length);
1280 
1281     /**
1282      * Transfers this buffer's data to the specified destination starting at
1283      * the current {@code readerIndex} until the destination's position
1284      * reaches its limit, and increases the {@code readerIndex} by the
1285      * number of the transferred bytes.
1286      *
1287      * @throws IndexOutOfBoundsException
1288      *         if {@code dst.remaining()} is greater than
1289      *            {@code this.readableBytes}
1290      */
1291     public abstract ByteBuf readBytes(ByteBuffer dst);
1292 
1293     /**
1294      * Transfers this buffer's data to the specified stream starting at the
1295      * current {@code readerIndex}.
1296      *
1297      * @param length the number of bytes to transfer
1298      *
1299      * @throws IndexOutOfBoundsException
1300      *         if {@code length} is greater than {@code this.readableBytes}
1301      * @throws IOException
1302      *         if the specified stream threw an exception during I/O
1303      */
1304     public abstract ByteBuf readBytes(OutputStream out, int length) throws IOException;
1305 
1306     /**
1307      * Transfers this buffer's data to the specified stream starting at the
1308      * current {@code readerIndex}.
1309      *
1310      * @param length the maximum number of bytes to transfer
1311      *
1312      * @return the actual number of bytes written out to the specified channel
1313      *
1314      * @throws IndexOutOfBoundsException
1315      *         if {@code length} is greater than {@code this.readableBytes}
1316      * @throws IOException
1317      *         if the specified channel threw an exception during I/O
1318      */
1319     public abstract int  readBytes(GatheringByteChannel out, int length) throws IOException;
1320 
1321     /**
1322      * Increases the current {@code readerIndex} by the specified
1323      * {@code length} in this buffer.
1324      *
1325      * @throws IndexOutOfBoundsException
1326      *         if {@code length} is greater than {@code this.readableBytes}
1327      */
1328     public abstract ByteBuf skipBytes(int length);
1329 
1330     /**
1331      * Sets the specified boolean at the current {@code writerIndex}
1332      * and increases the {@code writerIndex} by {@code 1} in this buffer.
1333      *
1334      * @throws IndexOutOfBoundsException
1335      *         if {@code this.writableBytes} is less than {@code 1}
1336      */
1337     public abstract ByteBuf writeBoolean(boolean value);
1338 
1339     /**
1340      * Sets the specified byte at the current {@code writerIndex}
1341      * and increases the {@code writerIndex} by {@code 1} in this buffer.
1342      * The 24 high-order bits of the specified value are ignored.
1343      *
1344      * @throws IndexOutOfBoundsException
1345      *         if {@code this.writableBytes} is less than {@code 1}
1346      */
1347     public abstract ByteBuf writeByte(int value);
1348 
1349     /**
1350      * Sets the specified 16-bit short integer at the current
1351      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1352      * in this buffer.  The 16 high-order bits of the specified value are ignored.
1353      *
1354      * @throws IndexOutOfBoundsException
1355      *         if {@code this.writableBytes} is less than {@code 2}
1356      */
1357     public abstract ByteBuf writeShort(int value);
1358 
1359     /**
1360      * Sets the specified 24-bit medium integer at the current
1361      * {@code writerIndex} and increases the {@code writerIndex} by {@code 3}
1362      * in this buffer.
1363      *
1364      * @throws IndexOutOfBoundsException
1365      *         if {@code this.writableBytes} is less than {@code 3}
1366      */
1367     public abstract ByteBuf writeMedium(int value);
1368 
1369     /**
1370      * Sets the specified 32-bit integer at the current {@code writerIndex}
1371      * and increases the {@code writerIndex} by {@code 4} in this buffer.
1372      *
1373      * @throws IndexOutOfBoundsException
1374      *         if {@code this.writableBytes} is less than {@code 4}
1375      */
1376     public abstract ByteBuf writeInt(int value);
1377 
1378     /**
1379      * Sets the specified 64-bit long integer at the current
1380      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1381      * in this buffer.
1382      *
1383      * @throws IndexOutOfBoundsException
1384      *         if {@code this.writableBytes} is less than {@code 8}
1385      */
1386     public abstract ByteBuf writeLong(long value);
1387 
1388     /**
1389      * Sets the specified 2-byte UTF-16 character at the current
1390      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1391      * in this buffer.  The 16 high-order bits of the specified value are ignored.
1392      *
1393      * @throws IndexOutOfBoundsException
1394      *         if {@code this.writableBytes} is less than {@code 2}
1395      */
1396     public abstract ByteBuf writeChar(int value);
1397 
1398     /**
1399      * Sets the specified 32-bit floating point number at the current
1400      * {@code writerIndex} and increases the {@code writerIndex} by {@code 4}
1401      * in this buffer.
1402      *
1403      * @throws IndexOutOfBoundsException
1404      *         if {@code this.writableBytes} is less than {@code 4}
1405      */
1406     public abstract ByteBuf writeFloat(float value);
1407 
1408     /**
1409      * Sets the specified 64-bit floating point number at the current
1410      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1411      * in this buffer.
1412      *
1413      * @throws IndexOutOfBoundsException
1414      *         if {@code this.writableBytes} is less than {@code 8}
1415      */
1416     public abstract ByteBuf writeDouble(double value);
1417 
1418     /**
1419      * Transfers the specified source buffer's data to this buffer starting at
1420      * the current {@code writerIndex} until the source buffer becomes
1421      * unreadable, and increases the {@code writerIndex} by the number of
1422      * the transferred bytes.  This method is basically same with
1423      * {@link #writeBytes(ByteBuf, int, int)}, except that this method
1424      * increases the {@code readerIndex} of the source buffer by the number of
1425      * the transferred bytes while {@link #writeBytes(ByteBuf, int, int)}
1426      * does not.
1427      *
1428      * @throws IndexOutOfBoundsException
1429      *         if {@code src.readableBytes} is greater than
1430      *            {@code this.writableBytes}
1431      */
1432     public abstract ByteBuf writeBytes(ByteBuf src);
1433 
1434     /**
1435      * Transfers the specified source buffer's data to this buffer starting at
1436      * the current {@code writerIndex} and increases the {@code writerIndex}
1437      * by the number of the transferred bytes (= {@code length}).  This method
1438      * is basically same with {@link #writeBytes(ByteBuf, int, int)},
1439      * except that this method increases the {@code readerIndex} of the source
1440      * buffer by the number of the transferred bytes (= {@code length}) while
1441      * {@link #writeBytes(ByteBuf, int, int)} does not.
1442      *
1443      * @param length the number of bytes to transfer
1444      *
1445      * @throws IndexOutOfBoundsException
1446      *         if {@code length} is greater than {@code this.writableBytes} or
1447      *         if {@code length} is greater then {@code src.readableBytes}
1448      */
1449     public abstract ByteBuf writeBytes(ByteBuf src, int length);
1450 
1451     /**
1452      * Transfers the specified source buffer's data to this buffer starting at
1453      * the current {@code writerIndex} and increases the {@code writerIndex}
1454      * by the number of the transferred bytes (= {@code length}).
1455      *
1456      * @param srcIndex the first index of the source
1457      * @param length   the number of bytes to transfer
1458      *
1459      * @throws IndexOutOfBoundsException
1460      *         if the specified {@code srcIndex} is less than {@code 0},
1461      *         if {@code srcIndex + length} is greater than
1462      *            {@code src.capacity}, or
1463      *         if {@code length} is greater than {@code this.writableBytes}
1464      */
1465     public abstract ByteBuf writeBytes(ByteBuf src, int srcIndex, int length);
1466 
1467     /**
1468      * Transfers the specified source array's data to this buffer starting at
1469      * the current {@code writerIndex} and increases the {@code writerIndex}
1470      * by the number of the transferred bytes (= {@code src.length}).
1471      *
1472      * @throws IndexOutOfBoundsException
1473      *         if {@code src.length} is greater than {@code this.writableBytes}
1474      */
1475     public abstract ByteBuf writeBytes(byte[] src);
1476 
1477     /**
1478      * Transfers the specified source array's data to this buffer starting at
1479      * the current {@code writerIndex} and increases the {@code writerIndex}
1480      * by the number of the transferred bytes (= {@code length}).
1481      *
1482      * @param srcIndex the first index of the source
1483      * @param length   the number of bytes to transfer
1484      *
1485      * @throws IndexOutOfBoundsException
1486      *         if the specified {@code srcIndex} is less than {@code 0},
1487      *         if {@code srcIndex + length} is greater than
1488      *            {@code src.length}, or
1489      *         if {@code length} is greater than {@code this.writableBytes}
1490      */
1491     public abstract ByteBuf writeBytes(byte[] src, int srcIndex, int length);
1492 
1493     /**
1494      * Transfers the specified source buffer's data to this buffer starting at
1495      * the current {@code writerIndex} until the source buffer's position
1496      * reaches its limit, and increases the {@code writerIndex} by the
1497      * number of the transferred bytes.
1498      *
1499      * @throws IndexOutOfBoundsException
1500      *         if {@code src.remaining()} is greater than
1501      *            {@code this.writableBytes}
1502      */
1503     public abstract ByteBuf writeBytes(ByteBuffer src);
1504 
1505     /**
1506      * Transfers the content of the specified stream to this buffer
1507      * starting at the current {@code writerIndex} and increases the
1508      * {@code writerIndex} by the number of the transferred bytes.
1509      *
1510      * @param length the number of bytes to transfer
1511      *
1512      * @return the actual number of bytes read in from the specified stream
1513      *
1514      * @throws IndexOutOfBoundsException
1515      *         if {@code length} is greater than {@code this.writableBytes}
1516      * @throws IOException
1517      *         if the specified stream threw an exception during I/O
1518      */
1519     public abstract int  writeBytes(InputStream in, int length) throws IOException;
1520 
1521     /**
1522      * Transfers the content of the specified channel to this buffer
1523      * starting at the current {@code writerIndex} and increases the
1524      * {@code writerIndex} by the number of the transferred bytes.
1525      *
1526      * @param length the maximum number of bytes to transfer
1527      *
1528      * @return the actual number of bytes read in from the specified channel
1529      *
1530      * @throws IndexOutOfBoundsException
1531      *         if {@code length} is greater than {@code this.writableBytes}
1532      * @throws IOException
1533      *         if the specified channel threw an exception during I/O
1534      */
1535     public abstract int  writeBytes(ScatteringByteChannel in, int length) throws IOException;
1536 
1537     /**
1538      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the current
1539      * {@code writerIndex} and increases the {@code writerIndex} by the
1540      * specified {@code length}.
1541      *
1542      * @param length the number of <tt>NUL</tt>s to write to the buffer
1543      *
1544      * @throws IndexOutOfBoundsException
1545      *         if {@code length} is greater than {@code this.writableBytes}
1546      */
1547     public abstract ByteBuf writeZero(int length);
1548 
1549     /**
1550      * Locates the first occurrence of the specified {@code value} in this
1551      * buffer.  The search takes place from the specified {@code fromIndex}
1552      * (inclusive)  to the specified {@code toIndex} (exclusive).
1553      * <p>
1554      * If {@code fromIndex} is greater than {@code toIndex}, the search is
1555      * performed in a reversed order.
1556      * <p>
1557      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1558      * this buffer.
1559      *
1560      * @return the absolute index of the first occurrence if found.
1561      *         {@code -1} otherwise.
1562      */
1563     public abstract int indexOf(int fromIndex, int toIndex, byte value);
1564 
1565     /**
1566      * Locates the first occurrence of the specified {@code value} in this
1567      * buffer.  The search takes place from the current {@code readerIndex}
1568      * (inclusive) to the current {@code writerIndex} (exclusive).
1569      * <p>
1570      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1571      * this buffer.
1572      *
1573      * @return the number of bytes between the current {@code readerIndex}
1574      *         and the first occurrence if found. {@code -1} otherwise.
1575      */
1576     public abstract int bytesBefore(byte value);
1577 
1578     /**
1579      * Locates the first occurrence of the specified {@code value} in this
1580      * buffer.  The search starts from the current {@code readerIndex}
1581      * (inclusive) and lasts for the specified {@code length}.
1582      * <p>
1583      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1584      * this buffer.
1585      *
1586      * @return the number of bytes between the current {@code readerIndex}
1587      *         and the first occurrence if found. {@code -1} otherwise.
1588      *
1589      * @throws IndexOutOfBoundsException
1590      *         if {@code length} is greater than {@code this.readableBytes}
1591      */
1592     public abstract int bytesBefore(int length, byte value);
1593 
1594     /**
1595      * Locates the first occurrence of the specified {@code value} in this
1596      * buffer.  The search starts from the specified {@code index} (inclusive)
1597      * and lasts for the specified {@code length}.
1598      * <p>
1599      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1600      * this buffer.
1601      *
1602      * @return the number of bytes between the specified {@code index}
1603      *         and the first occurrence if found. {@code -1} otherwise.
1604      *
1605      * @throws IndexOutOfBoundsException
1606      *         if {@code index + length} is greater than {@code this.capacity}
1607      */
1608     public abstract int bytesBefore(int index, int length, byte value);
1609 
1610     /**
1611      * Iterates over the readable bytes of this buffer with the specified {@code processor} in ascending order.
1612      *
1613      * @return {@code -1} if the processor iterated to or beyond the end of the readable bytes.
1614      *         The last-visited index If the {@link ByteBufProcessor#process(byte)} returned {@code false}.
1615      */
1616     public abstract int forEachByte(ByteBufProcessor processor);
1617 
1618     /**
1619      * Iterates over the specified area of this buffer with the specified {@code processor} in ascending order.
1620      * (i.e. {@code index}, {@code (index + 1)},  .. {@code (index + length - 1)})
1621      *
1622      * @return {@code -1} if the processor iterated to or beyond the end of the specified area.
1623      *         The last-visited index If the {@link ByteBufProcessor#process(byte)} returned {@code false}.
1624      */
1625     public abstract int forEachByte(int index, int length, ByteBufProcessor processor);
1626 
1627     /**
1628      * Iterates over the readable bytes of this buffer with the specified {@code processor} in descending order.
1629      *
1630      * @return {@code -1} if the processor iterated to or beyond the beginning of the readable bytes.
1631      *         The last-visited index If the {@link ByteBufProcessor#process(byte)} returned {@code false}.
1632      */
1633     public abstract int forEachByteDesc(ByteBufProcessor processor);
1634 
1635     /**
1636      * Iterates over the specified area of this buffer with the specified {@code processor} in descending order.
1637      * (i.e. {@code (index + length - 1)}, {@code (index + length - 2)}, ... {@code index})
1638      *
1639      *
1640      * @return {@code -1} if the processor iterated to or beyond the beginning of the specified area.
1641      *         The last-visited index If the {@link ByteBufProcessor#process(byte)} returned {@code false}.
1642      */
1643     public abstract int forEachByteDesc(int index, int length, ByteBufProcessor processor);
1644 
1645     /**
1646      * Returns a copy of this buffer's readable bytes.  Modifying the content
1647      * of the returned buffer or this buffer does not affect each other at all.
1648      * This method is identical to {@code buf.copy(buf.readerIndex(), buf.readableBytes())}.
1649      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1650      * this buffer.
1651      */
1652     public abstract ByteBuf copy();
1653 
1654     /**
1655      * Returns a copy of this buffer's sub-region.  Modifying the content of
1656      * the returned buffer or this buffer does not affect each other at all.
1657      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1658      * this buffer.
1659      */
1660     public abstract ByteBuf copy(int index, int length);
1661 
1662     /**
1663      * Returns a slice of this buffer's readable bytes. Modifying the content
1664      * of the returned buffer or this buffer affects each other's content
1665      * while they maintain separate indexes and marks.  This method is
1666      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
1667      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1668      * this buffer.
1669      * <p>
1670      * Also be aware that this method will NOT call {@link #retain()} and so the
1671      * reference count will NOT be increased.
1672      */
1673     public abstract ByteBuf slice();
1674 
1675     /**
1676      * Returns a slice of this buffer's sub-region. Modifying the content of
1677      * the returned buffer or this buffer affects each other's content while
1678      * they maintain separate indexes and marks.
1679      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1680      * this buffer.
1681      * <p>
1682      * Also be aware that this method will NOT call {@link #retain()} and so the
1683      * reference count will NOT be increased.
1684      */
1685     public abstract ByteBuf slice(int index, int length);
1686 
1687     /**
1688      * Returns a buffer which shares the whole region of this buffer.
1689      * Modifying the content of the returned buffer or this buffer affects
1690      * each other's content while they maintain separate indexes and marks.
1691      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1692      * this buffer.
1693      * <p>
1694      * The reader and writer marks will not be duplicated. Also be aware that this method will
1695      * NOT call {@link #retain()} and so the reference count will NOT be increased.
1696      * @return A buffer whose readable content is equivalent to the buffer returned by {@link #slice()}.
1697      * However this buffer will share the capacity of the underlying buffer, and therefore allows access to all of the
1698      * underlying content if necessary.
1699      */
1700     public abstract ByteBuf duplicate();
1701 
1702     /**
1703      * Returns the maximum number of NIO {@link ByteBuffer}s that consist this buffer.  Note that {@link #nioBuffers()}
1704      * or {@link #nioBuffers(int, int)} might return a less number of {@link ByteBuffer}s.
1705      *
1706      * @return {@code -1} if this buffer has no underlying {@link ByteBuffer}.
1707      *         the number of the underlying {@link ByteBuffer}s if this buffer has at least one underlying
1708      *         {@link ByteBuffer}.  Note that this method does not return {@code 0} to avoid confusion.
1709      *
1710      * @see #nioBuffer()
1711      * @see #nioBuffer(int, int)
1712      * @see #nioBuffers()
1713      * @see #nioBuffers(int, int)
1714      */
1715     public abstract int nioBufferCount();
1716 
1717     /**
1718      * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}. The returned buffer
1719      * either share or contains the copied content of this buffer, while changing the position
1720      * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
1721      * This method is identical to {@code buf.nioBuffer(buf.readerIndex(), buf.readableBytes())}.
1722      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
1723      * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
1724      * is a dynamic buffer and it adjusted its capacity.
1725      *
1726      * @throws UnsupportedOperationException
1727      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
1728      *
1729      * @see #nioBufferCount()
1730      * @see #nioBuffers()
1731      * @see #nioBuffers(int, int)
1732      */
1733     public abstract ByteBuffer nioBuffer();
1734 
1735     /**
1736      * Exposes this buffer's sub-region as an NIO {@link ByteBuffer}. The returned buffer
1737      * either share or contains the copied content of this buffer, while changing the position
1738      * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
1739      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
1740      * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
1741      * is a dynamic buffer and it adjusted its capacity.
1742      *
1743      * @throws UnsupportedOperationException
1744      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
1745      *
1746      * @see #nioBufferCount()
1747      * @see #nioBuffers()
1748      * @see #nioBuffers(int, int)
1749      */
1750     public abstract ByteBuffer nioBuffer(int index, int length);
1751 
1752     /**
1753      * Internal use only: Exposes the internal NIO buffer.
1754      */
1755     public abstract ByteBuffer internalNioBuffer(int index, int length);
1756 
1757     /**
1758      * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}'s. The returned buffer
1759      * either share or contains the copied content of this buffer, while changing the position
1760      * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
1761      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
1762      * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
1763      * is a dynamic buffer and it adjusted its capacity.
1764      *
1765      *
1766      * @throws UnsupportedOperationException
1767      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
1768      *
1769      * @see #nioBufferCount()
1770      * @see #nioBuffer()
1771      * @see #nioBuffer(int, int)
1772      */
1773     public abstract ByteBuffer[] nioBuffers();
1774 
1775     /**
1776      * Exposes this buffer's bytes as an NIO {@link ByteBuffer}'s for the specified index and length
1777      * The returned buffer either share or contains the copied content of this buffer, while changing
1778      * the position and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
1779      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer. Please note that the
1780      * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
1781      * buffer and it adjusted its capacity.
1782      *
1783      * @throws UnsupportedOperationException
1784      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
1785      *
1786      * @see #nioBufferCount()
1787      * @see #nioBuffer()
1788      * @see #nioBuffer(int, int)
1789      */
1790     public abstract ByteBuffer[] nioBuffers(int index, int length);
1791 
1792     /**
1793      * Returns {@code true} if and only if this buffer has a backing byte array.
1794      * If this method returns true, you can safely call {@link #array()} and
1795      * {@link #arrayOffset()}.
1796      */
1797     public abstract boolean hasArray();
1798 
1799     /**
1800      * Returns the backing byte array of this buffer.
1801      *
1802      * @throws UnsupportedOperationException
1803      *         if there no accessible backing byte array
1804      */
1805     public abstract byte[] array();
1806 
1807     /**
1808      * Returns the offset of the first byte within the backing byte array of
1809      * this buffer.
1810      *
1811      * @throws UnsupportedOperationException
1812      *         if there no accessible backing byte array
1813      */
1814     public abstract int arrayOffset();
1815 
1816     /**
1817      * Returns {@code true} if and only if this buffer has a reference to the low-level memory address that points
1818      * to the backing data.
1819      */
1820     public abstract boolean hasMemoryAddress();
1821 
1822     /**
1823      * Returns the low-level memory address that point to the first byte of ths backing data.
1824      *
1825      * @throws UnsupportedOperationException
1826      *         if this buffer does not support accessing the low-level memory address
1827      */
1828     public abstract long memoryAddress();
1829 
1830     /**
1831      * Decodes this buffer's readable bytes into a string with the specified
1832      * character set name.  This method is identical to
1833      * {@code buf.toString(buf.readerIndex(), buf.readableBytes(), charsetName)}.
1834      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1835      * this buffer.
1836      *
1837      * @throws UnsupportedCharsetException
1838      *         if the specified character set name is not supported by the
1839      *         current VM
1840      */
1841     public abstract String toString(Charset charset);
1842 
1843     /**
1844      * Decodes this buffer's sub-region into a string with the specified
1845      * character set.  This method does not modify {@code readerIndex} or
1846      * {@code writerIndex} of this buffer.
1847      */
1848     public abstract String toString(int index, int length, Charset charset);
1849 
1850     /**
1851      * Returns a hash code which was calculated from the content of this
1852      * buffer.  If there's a byte array which is
1853      * {@linkplain #equals(Object) equal to} this array, both arrays should
1854      * return the same value.
1855      */
1856     @Override
1857     public abstract int hashCode();
1858 
1859     /**
1860      * Determines if the content of the specified buffer is identical to the
1861      * content of this array.  'Identical' here means:
1862      * <ul>
1863      * <li>the size of the contents of the two buffers are same and</li>
1864      * <li>every single byte of the content of the two buffers are same.</li>
1865      * </ul>
1866      * Please note that it does not compare {@link #readerIndex()} nor
1867      * {@link #writerIndex()}.  This method also returns {@code false} for
1868      * {@code null} and an object which is not an instance of
1869      * {@link ByteBuf} type.
1870      */
1871     @Override
1872     public abstract boolean equals(Object obj);
1873 
1874     /**
1875      * Compares the content of the specified buffer to the content of this
1876      * buffer. Comparison is performed in the same manner with the string
1877      * comparison functions of various languages such as {@code strcmp},
1878      * {@code memcmp} and {@link String#compareTo(String)}.
1879      */
1880     @Override
1881     public abstract int compareTo(ByteBuf buffer);
1882 
1883     /**
1884      * Returns the string representation of this buffer.  This method does not
1885      * necessarily return the whole content of the buffer but returns
1886      * the values of the key properties such as {@link #readerIndex()},
1887      * {@link #writerIndex()} and {@link #capacity()}.
1888      */
1889     @Override
1890     public abstract String toString();
1891 
1892     @Override
1893     public abstract ByteBuf retain(int increment);
1894 
1895     @Override
1896     public abstract ByteBuf retain();
1897 }