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