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.ByteProcessor;
19  import io.netty.util.ReferenceCounted;
20  
21  import java.io.IOException;
22  import java.io.InputStream;
23  import java.io.OutputStream;
24  import java.nio.ByteBuffer;
25  import java.nio.ByteOrder;
26  import java.nio.channels.FileChannel;
27  import java.nio.channels.GatheringByteChannel;
28  import java.nio.channels.ScatteringByteChannel;
29  import java.nio.charset.Charset;
30  import java.nio.charset.UnsupportedCharsetException;
31  
32  /**
33   * A random and sequential accessible sequence of zero or more bytes (octets).
34   * This interface provides an abstract view for one or more primitive byte
35   * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}.
36   *
37   * <h3>Creation of a buffer</h3>
38   *
39   * It is recommended to create a new buffer using the helper methods in
40   * {@link Unpooled} rather than calling an individual implementation's
41   * constructor.
42   *
43   * <h3>Random Access Indexing</h3>
44   *
45   * Just like an ordinary primitive byte array, {@link ByteBuf} uses
46   * <a href="http://en.wikipedia.org/wiki/Zero-based_numbering">zero-based indexing</a>.
47   * It means the index of the first byte is always {@code 0} and the index of the last byte is
48   * always {@link #capacity() capacity - 1}.  For example, to iterate all bytes of a buffer, you
49   * can do the following, regardless of its internal implementation:
50   *
51   * <pre>
52   * {@link ByteBuf} buffer = ...;
53   * for (int i = 0; i &lt; buffer.capacity(); i ++) {
54   *     byte b = buffer.getByte(i);
55   *     System.out.println((char) b);
56   * }
57   * </pre>
58   *
59   * <h3>Sequential Access Indexing</h3>
60   *
61   * {@link ByteBuf} provides two pointer variables to support sequential
62   * read and write operations - {@link #readerIndex() readerIndex} for a read
63   * operation and {@link #writerIndex() writerIndex} for a write operation
64   * respectively.  The following diagram shows how a buffer is segmented into
65   * three areas by the two pointers:
66   *
67   * <pre>
68   *      +-------------------+------------------+------------------+
69   *      | discardable bytes |  readable bytes  |  writable bytes  |
70   *      |                   |     (CONTENT)    |                  |
71   *      +-------------------+------------------+------------------+
72   *      |                   |                  |                  |
73   *      0      <=      readerIndex   <=   writerIndex    <=    capacity
74   * </pre>
75   *
76   * <h4>Readable bytes (the actual content)</h4>
77   *
78   * This segment is where the actual data is stored.  Any operation whose name
79   * starts with {@code read} or {@code skip} will get or skip the data at the
80   * current {@link #readerIndex() readerIndex} and increase it by the number of
81   * read bytes.  If the argument of the read operation is also a
82   * {@link ByteBuf} and no destination index is specified, the specified
83   * buffer's {@link #writerIndex() writerIndex} is increased together.
84   * <p>
85   * If there's not enough content left, {@link IndexOutOfBoundsException} is
86   * raised.  The default value of newly allocated, wrapped or copied buffer's
87   * {@link #readerIndex() readerIndex} is {@code 0}.
88   *
89   * <pre>
90   * // Iterates the readable bytes of a buffer.
91   * {@link ByteBuf} buffer = ...;
92   * while (buffer.isReadable()) {
93   *     System.out.println(buffer.readByte());
94   * }
95   * </pre>
96   *
97   * <h4>Writable bytes</h4>
98   *
99   * This segment is a undefined space which needs to be filled.  Any operation
100  * whose name starts with {@code write} will write the data at the current
101  * {@link #writerIndex() writerIndex} and increase it by the number of written
102  * bytes.  If the argument of the write operation is also a {@link ByteBuf},
103  * and no source index is specified, the specified buffer's
104  * {@link #readerIndex() readerIndex} is increased together.
105  * <p>
106  * If there's not enough writable bytes left, {@link IndexOutOfBoundsException}
107  * is raised.  The default value of newly allocated buffer's
108  * {@link #writerIndex() writerIndex} is {@code 0}.  The default value of
109  * wrapped or copied buffer's {@link #writerIndex() writerIndex} is the
110  * {@link #capacity() capacity} of the buffer.
111  *
112  * <pre>
113  * // Fills the writable bytes of a buffer with random integers.
114  * {@link ByteBuf} buffer = ...;
115  * while (buffer.maxWritableBytes() >= 4) {
116  *     buffer.writeInt(random.nextInt());
117  * }
118  * </pre>
119  *
120  * <h4>Discardable bytes</h4>
121  *
122  * This segment contains the bytes which were read already by a read operation.
123  * Initially, the size of this segment is {@code 0}, but its size increases up
124  * to the {@link #writerIndex() writerIndex} as read operations are executed.
125  * The read bytes can be discarded by calling {@link #discardReadBytes()} to
126  * reclaim unused area as depicted by the following diagram:
127  *
128  * <pre>
129  *  BEFORE discardReadBytes()
130  *
131  *      +-------------------+------------------+------------------+
132  *      | discardable bytes |  readable bytes  |  writable bytes  |
133  *      +-------------------+------------------+------------------+
134  *      |                   |                  |                  |
135  *      0      <=      readerIndex   <=   writerIndex    <=    capacity
136  *
137  *
138  *  AFTER discardReadBytes()
139  *
140  *      +------------------+--------------------------------------+
141  *      |  readable bytes  |    writable bytes (got more space)   |
142  *      +------------------+--------------------------------------+
143  *      |                  |                                      |
144  * readerIndex (0) <= writerIndex (decreased)        <=        capacity
145  * </pre>
146  *
147  * Please note that there is no guarantee about the content of writable bytes
148  * after calling {@link #discardReadBytes()}.  The writable bytes will not be
149  * moved in most cases and could even be filled with completely different data
150  * depending on the underlying buffer implementation.
151  *
152  * <h4>Clearing the buffer indexes</h4>
153  *
154  * You can set both {@link #readerIndex() readerIndex} and
155  * {@link #writerIndex() writerIndex} to {@code 0} by calling {@link #clear()}.
156  * It does not clear the buffer content (e.g. filling with {@code 0}) but just
157  * clears the two pointers.  Please also note that the semantic of this
158  * operation is different from {@link ByteBuffer#clear()}.
159  *
160  * <pre>
161  *  BEFORE clear()
162  *
163  *      +-------------------+------------------+------------------+
164  *      | discardable bytes |  readable bytes  |  writable bytes  |
165  *      +-------------------+------------------+------------------+
166  *      |                   |                  |                  |
167  *      0      <=      readerIndex   <=   writerIndex    <=    capacity
168  *
169  *
170  *  AFTER clear()
171  *
172  *      +---------------------------------------------------------+
173  *      |             writable bytes (got more space)             |
174  *      +---------------------------------------------------------+
175  *      |                                                         |
176  *      0 = readerIndex = writerIndex            <=            capacity
177  * </pre>
178  *
179  * <h3>Search operations</h3>
180  *
181  * For simple single-byte searches, use {@link #indexOf(int, int, byte)} and {@link #bytesBefore(int, int, byte)}.
182  * {@link #bytesBefore(byte)} is especially useful when you deal with a {@code NUL}-terminated string.
183  * For complicated searches, use {@link #forEachByte(int, int, ByteProcessor)} with a {@link ByteProcessor}
184  * implementation.
185  *
186  * <h3>Mark and reset</h3>
187  *
188  * There are two marker indexes in every buffer. One is for storing
189  * {@link #readerIndex() readerIndex} and the other is for storing
190  * {@link #writerIndex() writerIndex}.  You can always reposition one of the
191  * two indexes by calling a reset method.  It works in a similar fashion to
192  * the mark and reset methods in {@link InputStream} except that there's no
193  * {@code readlimit}.
194  *
195  * <h3>Derived buffers</h3>
196  *
197  * You can create a view of an existing buffer by calling one of the following methods:
198  * <ul>
199  *   <li>{@link #duplicate()}</li>
200  *   <li>{@link #slice()}</li>
201  *   <li>{@link #slice(int, int)}</li>
202  *   <li>{@link #readSlice(int)}</li>
203  *   <li>{@link #retainedDuplicate()}</li>
204  *   <li>{@link #retainedSlice()}</li>
205  *   <li>{@link #retainedSlice(int, int)}</li>
206  *   <li>{@link #readRetainedSlice(int)}</li>
207  * </ul>
208  * A derived buffer will have an independent {@link #readerIndex() readerIndex},
209  * {@link #writerIndex() writerIndex} and marker indexes, while it shares
210  * other internal data representation, just like a NIO buffer does.
211  * <p>
212  * In case a completely fresh copy of an existing buffer is required, please
213  * call {@link #copy()} method instead.
214  *
215  * <h4>Non-retained and retained derived buffers</h4>
216  *
217  * Note that the {@link #duplicate()}, {@link #slice()}, {@link #slice(int, int)} and {@link #readSlice(int)} does NOT
218  * call {@link #retain()} on the returned derived buffer, and thus its reference count will NOT be increased. If you
219  * need to create a derived buffer with increased reference count, consider using {@link #retainedDuplicate()},
220  * {@link #retainedSlice()}, {@link #retainedSlice(int, int)} and {@link #readRetainedSlice(int)} which may return
221  * a buffer implementation that produces less garbage.
222  *
223  * <h3>Conversion to existing JDK types</h3>
224  *
225  * <h4>Byte array</h4>
226  *
227  * If a {@link ByteBuf} is backed by a byte array (i.e. {@code byte[]}),
228  * you can access it directly via the {@link #array()} method.  To determine
229  * if a buffer is backed by a byte array, {@link #hasArray()} should be used.
230  *
231  * <h4>NIO Buffers</h4>
232  *
233  * If a {@link ByteBuf} can be converted into an NIO {@link ByteBuffer} which shares its
234  * content (i.e. view buffer), you can get it via the {@link #nioBuffer()} method.  To determine
235  * if a buffer can be converted into an NIO buffer, use {@link #nioBufferCount()}.
236  *
237  * <h4>Strings</h4>
238  *
239  * Various {@link #toString(Charset)} methods convert a {@link ByteBuf}
240  * into a {@link String}.  Please note that {@link #toString()} is not a
241  * conversion method.
242  *
243  * <h4>I/O Streams</h4>
244  *
245  * Please refer to {@link ByteBufInputStream} and
246  * {@link ByteBufOutputStream}.
247  */
248 @SuppressWarnings("ClassMayBeInterface")
249 public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
250 
251     /**
252      * Returns the number of bytes (octets) this buffer can contain.
253      */
254     public abstract int capacity();
255 
256     /**
257      * Adjusts the capacity of this buffer.  If the {@code newCapacity} is less than the current
258      * capacity, the content of this buffer is truncated.  If the {@code newCapacity} is greater
259      * than the current capacity, the buffer is appended with unspecified data whose length is
260      * {@code (newCapacity - currentCapacity)}.
261      */
262     public abstract ByteBuf capacity(int newCapacity);
263 
264     /**
265      * Returns the maximum allowed capacity of this buffer.  If a user attempts to increase the
266      * capacity of this buffer beyond the maximum capacity using {@link #capacity(int)} or
267      * {@link #ensureWritable(int)}, those methods will raise an
268      * {@link IllegalArgumentException}.
269      */
270     public abstract int maxCapacity();
271 
272     /**
273      * Returns the {@link ByteBufAllocator} which created this buffer.
274      */
275     public abstract ByteBufAllocator alloc();
276 
277     /**
278      * Returns the <a href="http://en.wikipedia.org/wiki/Endianness">endianness</a>
279      * of this buffer.
280      *
281      * @deprecated use the Little Endian accessors, e.g. {@code getShortLE}, {@code getIntLE}
282      * instead of creating a buffer with swapped {@code endianness}.
283      */
284     @Deprecated
285     public abstract ByteOrder order();
286 
287     /**
288      * Returns a buffer with the specified {@code endianness} which shares the whole region,
289      * indexes, and marks of this buffer.  Modifying the content, the indexes, or the marks of the
290      * returned buffer or this buffer affects each other's content, indexes, and marks.  If the
291      * specified {@code endianness} is identical to this buffer's byte order, this method can
292      * return {@code this}.  This method does not modify {@code readerIndex} or {@code writerIndex}
293      * of this buffer.
294      *
295      * @deprecated use the Little Endian accessors, e.g. {@code getShortLE}, {@code getIntLE}
296      * instead of creating a buffer with swapped {@code endianness}.
297      */
298     @Deprecated
299     public abstract ByteBuf order(ByteOrder endianness);
300 
301     /**
302      * Return the underlying buffer instance if this buffer is a wrapper of another buffer.
303      *
304      * @return {@code null} if this buffer is not a wrapper
305      */
306     public abstract ByteBuf unwrap();
307 
308     /**
309      * Returns {@code true} if and only if this buffer is backed by an
310      * NIO direct buffer.
311      */
312     public abstract boolean isDirect();
313 
314     /**
315      * Returns {@code true} if and only if this buffer is read-only.
316      */
317     public abstract boolean isReadOnly();
318 
319     /**
320      * Returns a read-only version of this buffer.
321      */
322     public abstract ByteBuf asReadOnly();
323 
324     /**
325      * Returns the {@code readerIndex} of this buffer.
326      */
327     public abstract int readerIndex();
328 
329     /**
330      * Sets the {@code readerIndex} of this buffer.
331      *
332      * @throws IndexOutOfBoundsException
333      *         if the specified {@code readerIndex} is
334      *            less than {@code 0} or
335      *            greater than {@code this.writerIndex}
336      */
337     public abstract ByteBuf readerIndex(int readerIndex);
338 
339     /**
340      * Returns the {@code writerIndex} of this buffer.
341      */
342     public abstract int writerIndex();
343 
344     /**
345      * Sets the {@code writerIndex} of this buffer.
346      *
347      * @throws IndexOutOfBoundsException
348      *         if the specified {@code writerIndex} is
349      *            less than {@code this.readerIndex} or
350      *            greater than {@code this.capacity}
351      */
352     public abstract ByteBuf writerIndex(int writerIndex);
353 
354     /**
355      * Sets the {@code readerIndex} and {@code writerIndex} of this buffer
356      * in one shot.  This method is useful when you have to worry about the
357      * invocation order of {@link #readerIndex(int)} and {@link #writerIndex(int)}
358      * methods.  For example, the following code will fail:
359      *
360      * <pre>
361      * // Create a buffer whose readerIndex, writerIndex and capacity are
362      * // 0, 0 and 8 respectively.
363      * {@link ByteBuf} buf = {@link Unpooled}.buffer(8);
364      *
365      * // IndexOutOfBoundsException is thrown because the specified
366      * // readerIndex (2) cannot be greater than the current writerIndex (0).
367      * buf.readerIndex(2);
368      * buf.writerIndex(4);
369      * </pre>
370      *
371      * The following code will also fail:
372      *
373      * <pre>
374      * // Create a buffer whose readerIndex, writerIndex and capacity are
375      * // 0, 8 and 8 respectively.
376      * {@link ByteBuf} buf = {@link Unpooled}.wrappedBuffer(new byte[8]);
377      *
378      * // readerIndex becomes 8.
379      * buf.readLong();
380      *
381      * // IndexOutOfBoundsException is thrown because the specified
382      * // writerIndex (4) cannot be less than the current readerIndex (8).
383      * buf.writerIndex(4);
384      * buf.readerIndex(2);
385      * </pre>
386      *
387      * By contrast, this method guarantees that it never
388      * throws an {@link IndexOutOfBoundsException} as long as the specified
389      * indexes meet basic constraints, regardless what the current index
390      * values of the buffer are:
391      *
392      * <pre>
393      * // No matter what the current state of the buffer is, the following
394      * // call always succeeds as long as the capacity of the buffer is not
395      * // less than 4.
396      * buf.setIndex(2, 4);
397      * </pre>
398      *
399      * @throws IndexOutOfBoundsException
400      *         if the specified {@code readerIndex} is less than 0,
401      *         if the specified {@code writerIndex} is less than the specified
402      *         {@code readerIndex} or if the specified {@code writerIndex} is
403      *         greater than {@code this.capacity}
404      */
405     public abstract ByteBuf setIndex(int readerIndex, int writerIndex);
406 
407     /**
408      * Returns the number of readable bytes which is equal to
409      * {@code (this.writerIndex - this.readerIndex)}.
410      */
411     public abstract int readableBytes();
412 
413     /**
414      * Returns the number of writable bytes which is equal to
415      * {@code (this.capacity - this.writerIndex)}.
416      */
417     public abstract int writableBytes();
418 
419     /**
420      * Returns the maximum possible number of writable bytes, which is equal to
421      * {@code (this.maxCapacity - this.writerIndex)}.
422      */
423     public abstract int maxWritableBytes();
424 
425     /**
426      * Returns {@code true}
427      * if and only if {@code (this.writerIndex - this.readerIndex)} is greater
428      * than {@code 0}.
429      */
430     public abstract boolean isReadable();
431 
432     /**
433      * Returns {@code true} if and only if this buffer contains equal to or more than the specified number of elements.
434      */
435     public abstract boolean isReadable(int size);
436 
437     /**
438      * Returns {@code true}
439      * if and only if {@code (this.capacity - this.writerIndex)} is greater
440      * than {@code 0}.
441      */
442     public abstract boolean isWritable();
443 
444     /**
445      * Returns {@code true} if and only if this buffer has enough room to allow writing the specified number of
446      * elements.
447      */
448     public abstract boolean isWritable(int size);
449 
450     /**
451      * Sets the {@code readerIndex} and {@code writerIndex} of this buffer to
452      * {@code 0}.
453      * This method is identical to {@link #setIndex(int, int) setIndex(0, 0)}.
454      * <p>
455      * Please note that the behavior of this method is different
456      * from that of NIO buffer, which sets the {@code limit} to
457      * the {@code capacity} of the buffer.
458      */
459     public abstract ByteBuf clear();
460 
461     /**
462      * Marks the current {@code readerIndex} in this buffer.  You can
463      * reposition the current {@code readerIndex} to the marked
464      * {@code readerIndex} by calling {@link #resetReaderIndex()}.
465      * The initial value of the marked {@code readerIndex} is {@code 0}.
466      */
467     public abstract ByteBuf markReaderIndex();
468 
469     /**
470      * Repositions the current {@code readerIndex} to the marked
471      * {@code readerIndex} in this buffer.
472      *
473      * @throws IndexOutOfBoundsException
474      *         if the current {@code writerIndex} is less than the marked
475      *         {@code readerIndex}
476      */
477     public abstract ByteBuf resetReaderIndex();
478 
479     /**
480      * Marks the current {@code writerIndex} in this buffer.  You can
481      * reposition the current {@code writerIndex} to the marked
482      * {@code writerIndex} by calling {@link #resetWriterIndex()}.
483      * The initial value of the marked {@code writerIndex} is {@code 0}.
484      */
485     public abstract ByteBuf markWriterIndex();
486 
487     /**
488      * Repositions the current {@code writerIndex} to the marked
489      * {@code writerIndex} in this buffer.
490      *
491      * @throws IndexOutOfBoundsException
492      *         if the current {@code readerIndex} is greater than the marked
493      *         {@code writerIndex}
494      */
495     public abstract ByteBuf resetWriterIndex();
496 
497     /**
498      * Discards the bytes between the 0th index and {@code readerIndex}.
499      * It moves the bytes between {@code readerIndex} and {@code writerIndex}
500      * to the 0th index, and sets {@code readerIndex} and {@code writerIndex}
501      * to {@code 0} and {@code oldWriterIndex - oldReaderIndex} respectively.
502      * <p>
503      * Please refer to the class documentation for more detailed explanation.
504      */
505     public abstract ByteBuf discardReadBytes();
506 
507     /**
508      * Similar to {@link ByteBuf#discardReadBytes()} except that this method might discard
509      * some, all, or none of read bytes depending on its internal implementation to reduce
510      * overall memory bandwidth consumption at the cost of potentially additional memory
511      * consumption.
512      */
513     public abstract ByteBuf discardSomeReadBytes();
514 
515     /**
516      * Makes sure the number of {@linkplain #writableBytes() the writable bytes}
517      * is equal to or greater than the specified value.  If there is enough
518      * writable bytes in this buffer, this method returns with no side effect.
519      * Otherwise, it raises an {@link IllegalArgumentException}.
520      *
521      * @param minWritableBytes
522      *        the expected minimum number of writable bytes
523      * @throws IndexOutOfBoundsException
524      *         if {@link #writerIndex()} + {@code minWritableBytes} &gt; {@link #maxCapacity()}
525      */
526     public abstract ByteBuf ensureWritable(int minWritableBytes);
527 
528     /**
529      * Tries to make sure the number of {@linkplain #writableBytes() the writable bytes}
530      * is equal to or greater than the specified value.  Unlike {@link #ensureWritable(int)},
531      * this method does not raise an exception but returns a code.
532      *
533      * @param minWritableBytes
534      *        the expected minimum number of writable bytes
535      * @param force
536      *        When {@link #writerIndex()} + {@code minWritableBytes} &gt; {@link #maxCapacity()}:
537      *        <ul>
538      *        <li>{@code true} - the capacity of the buffer is expanded to {@link #maxCapacity()}</li>
539      *        <li>{@code false} - the capacity of the buffer is unchanged</li>
540      *        </ul>
541      * @return {@code 0} if the buffer has enough writable bytes, and its capacity is unchanged.
542      *         {@code 1} if the buffer does not have enough bytes, and its capacity is unchanged.
543      *         {@code 2} if the buffer has enough writable bytes, and its capacity has been increased.
544      *         {@code 3} if the buffer does not have enough bytes, but its capacity has been
545      *                   increased to its maximum.
546      */
547     public abstract int ensureWritable(int minWritableBytes, boolean force);
548 
549     /**
550      * Gets a boolean at the specified absolute (@code index) in this buffer.
551      * This method does not modify the {@code readerIndex} or {@code writerIndex}
552      * of this buffer.
553      *
554      * @throws IndexOutOfBoundsException
555      *         if the specified {@code index} is less than {@code 0} or
556      *         {@code index + 1} is greater than {@code this.capacity}
557      */
558     public abstract boolean getBoolean(int index);
559 
560     /**
561      * Gets a byte at the specified absolute {@code index} in this buffer.
562      * This method does not modify {@code readerIndex} or {@code writerIndex} of
563      * this buffer.
564      *
565      * @throws IndexOutOfBoundsException
566      *         if the specified {@code index} is less than {@code 0} or
567      *         {@code index + 1} is greater than {@code this.capacity}
568      */
569     public abstract byte  getByte(int index);
570 
571     /**
572      * Gets an unsigned byte at the specified absolute {@code index} in this
573      * buffer.  This method does not modify {@code readerIndex} or
574      * {@code writerIndex} of this buffer.
575      *
576      * @throws IndexOutOfBoundsException
577      *         if the specified {@code index} is less than {@code 0} or
578      *         {@code index + 1} is greater than {@code this.capacity}
579      */
580     public abstract short getUnsignedByte(int index);
581 
582     /**
583      * Gets a 16-bit short integer at the specified absolute {@code index} in
584      * this buffer.  This method does not modify {@code readerIndex} or
585      * {@code writerIndex} of this buffer.
586      *
587      * @throws IndexOutOfBoundsException
588      *         if the specified {@code index} is less than {@code 0} or
589      *         {@code index + 2} is greater than {@code this.capacity}
590      */
591     public abstract short getShort(int index);
592 
593     /**
594      * Gets a 16-bit short integer at the specified absolute {@code index} in
595      * this buffer in Little Endian Byte Order. This method does not modify
596      * {@code readerIndex} or {@code writerIndex} of this buffer.
597      *
598      * @throws IndexOutOfBoundsException
599      *         if the specified {@code index} is less than {@code 0} or
600      *         {@code index + 2} is greater than {@code this.capacity}
601      */
602     public abstract short getShortLE(int index);
603 
604     /**
605      * Gets an unsigned 16-bit short integer at the specified absolute
606      * {@code index} in this buffer.  This method does not modify
607      * {@code readerIndex} or {@code writerIndex} of this buffer.
608      *
609      * @throws IndexOutOfBoundsException
610      *         if the specified {@code index} is less than {@code 0} or
611      *         {@code index + 2} is greater than {@code this.capacity}
612      */
613     public abstract int getUnsignedShort(int index);
614 
615     /**
616      * Gets an unsigned 16-bit short integer at the specified absolute
617      * {@code index} in this buffer in Little Endian Byte Order.
618      * This method does not modify {@code readerIndex} or
619      * {@code writerIndex} of this buffer.
620      *
621      * @throws IndexOutOfBoundsException
622      *         if the specified {@code index} is less than {@code 0} or
623      *         {@code index + 2} is greater than {@code this.capacity}
624      */
625     public abstract int getUnsignedShortLE(int index);
626 
627     /**
628      * Gets a 24-bit medium integer at the specified absolute {@code index} in
629      * this buffer.  This method does not modify {@code readerIndex} or
630      * {@code writerIndex} of this buffer.
631      *
632      * @throws IndexOutOfBoundsException
633      *         if the specified {@code index} is less than {@code 0} or
634      *         {@code index + 3} is greater than {@code this.capacity}
635      */
636     public abstract int   getMedium(int index);
637 
638     /**
639      * Gets a 24-bit medium integer at the specified absolute {@code index} in
640      * this buffer in the Little Endian Byte Order. This method does not
641      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
642      *
643      * @throws IndexOutOfBoundsException
644      *         if the specified {@code index} is less than {@code 0} or
645      *         {@code index + 3} is greater than {@code this.capacity}
646      */
647     public abstract int getMediumLE(int index);
648 
649     /**
650      * Gets an unsigned 24-bit medium integer at the specified absolute
651      * {@code index} in this buffer.  This method does not modify
652      * {@code readerIndex} or {@code writerIndex} of this buffer.
653      *
654      * @throws IndexOutOfBoundsException
655      *         if the specified {@code index} is less than {@code 0} or
656      *         {@code index + 3} is greater than {@code this.capacity}
657      */
658     public abstract int   getUnsignedMedium(int index);
659 
660     /**
661      * Gets an unsigned 24-bit medium integer at the specified absolute
662      * {@code index} in this buffer in Little Endian Byte Order.
663      * This method does not modify {@code readerIndex} or
664      * {@code writerIndex} of this buffer.
665      *
666      * @throws IndexOutOfBoundsException
667      *         if the specified {@code index} is less than {@code 0} or
668      *         {@code index + 3} is greater than {@code this.capacity}
669      */
670     public abstract int   getUnsignedMediumLE(int index);
671 
672     /**
673      * Gets a 32-bit integer at the specified absolute {@code index} in
674      * this buffer.  This method does not modify {@code readerIndex} or
675      * {@code writerIndex} of this buffer.
676      *
677      * @throws IndexOutOfBoundsException
678      *         if the specified {@code index} is less than {@code 0} or
679      *         {@code index + 4} is greater than {@code this.capacity}
680      */
681     public abstract int   getInt(int index);
682 
683     /**
684      * Gets a 32-bit integer at the specified absolute {@code index} in
685      * this buffer with Little Endian Byte Order. This method does not
686      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
687      *
688      * @throws IndexOutOfBoundsException
689      *         if the specified {@code index} is less than {@code 0} or
690      *         {@code index + 4} is greater than {@code this.capacity}
691      */
692     public abstract int   getIntLE(int index);
693 
694     /**
695      * Gets an unsigned 32-bit integer at the specified absolute {@code index}
696      * in this buffer.  This method does not modify {@code readerIndex} or
697      * {@code writerIndex} of this buffer.
698      *
699      * @throws IndexOutOfBoundsException
700      *         if the specified {@code index} is less than {@code 0} or
701      *         {@code index + 4} is greater than {@code this.capacity}
702      */
703     public abstract long  getUnsignedInt(int index);
704 
705     /**
706      * Gets an unsigned 32-bit integer at the specified absolute {@code index}
707      * in this buffer in Little Endian Byte Order. This method does not
708      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
709      *
710      * @throws IndexOutOfBoundsException
711      *         if the specified {@code index} is less than {@code 0} or
712      *         {@code index + 4} is greater than {@code this.capacity}
713      */
714     public abstract long  getUnsignedIntLE(int index);
715 
716     /**
717      * Gets a 64-bit long integer at the specified absolute {@code index} in
718      * this buffer.  This method does not modify {@code readerIndex} or
719      * {@code writerIndex} of this buffer.
720      *
721      * @throws IndexOutOfBoundsException
722      *         if the specified {@code index} is less than {@code 0} or
723      *         {@code index + 8} is greater than {@code this.capacity}
724      */
725     public abstract long  getLong(int index);
726 
727     /**
728      * Gets a 64-bit long integer at the specified absolute {@code index} in
729      * this buffer in Little Endian Byte Order. This method does not
730      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
731      *
732      * @throws IndexOutOfBoundsException
733      *         if the specified {@code index} is less than {@code 0} or
734      *         {@code index + 8} is greater than {@code this.capacity}
735      */
736     public abstract long  getLongLE(int index);
737 
738     /**
739      * Gets a 2-byte UTF-16 character at the specified absolute
740      * {@code index} in this buffer.  This method does not modify
741      * {@code readerIndex} or {@code writerIndex} of this buffer.
742      *
743      * @throws IndexOutOfBoundsException
744      *         if the specified {@code index} is less than {@code 0} or
745      *         {@code index + 2} is greater than {@code this.capacity}
746      */
747     public abstract char  getChar(int index);
748 
749     /**
750      * Gets a 32-bit floating point number at the specified absolute
751      * {@code index} in this buffer.  This method does not modify
752      * {@code readerIndex} or {@code writerIndex} of this buffer.
753      *
754      * @throws IndexOutOfBoundsException
755      *         if the specified {@code index} is less than {@code 0} or
756      *         {@code index + 4} is greater than {@code this.capacity}
757      */
758     public abstract float getFloat(int index);
759 
760     /**
761      * Gets a 32-bit floating point number at the specified absolute
762      * {@code index} in this buffer in Little Endian Byte Order.
763      * This method does not modify {@code readerIndex} or
764      * {@code writerIndex} of this buffer.
765      *
766      * @throws IndexOutOfBoundsException
767      *         if the specified {@code index} is less than {@code 0} or
768      *         {@code index + 4} is greater than {@code this.capacity}
769      */
770     public float getFloatLE(int index) {
771         return Float.intBitsToFloat(getIntLE(index));
772     }
773 
774     /**
775      * Gets a 64-bit floating point number at the specified absolute
776      * {@code index} in this buffer.  This method does not modify
777      * {@code readerIndex} or {@code writerIndex} of this buffer.
778      *
779      * @throws IndexOutOfBoundsException
780      *         if the specified {@code index} is less than {@code 0} or
781      *         {@code index + 8} is greater than {@code this.capacity}
782      */
783     public abstract double getDouble(int index);
784 
785     /**
786      * Gets a 64-bit floating point number at the specified absolute
787      * {@code index} in this buffer in Little Endian Byte Order.
788      * This method does not modify {@code readerIndex} or
789      * {@code writerIndex} of this buffer.
790      *
791      * @throws IndexOutOfBoundsException
792      *         if the specified {@code index} is less than {@code 0} or
793      *         {@code index + 8} is greater than {@code this.capacity}
794      */
795     public double getDoubleLE(int index) {
796         return Double.longBitsToDouble(getLongLE(index));
797     }
798 
799     /**
800      * Transfers this buffer's data to the specified destination starting at
801      * the specified absolute {@code index} until the destination becomes
802      * non-writable.  This method is basically same with
803      * {@link #getBytes(int, ByteBuf, int, int)}, except that this
804      * method increases the {@code writerIndex} of the destination by the
805      * number of the transferred bytes while
806      * {@link #getBytes(int, ByteBuf, int, int)} does not.
807      * This method does not modify {@code readerIndex} or {@code writerIndex} of
808      * the source buffer (i.e. {@code this}).
809      *
810      * @throws IndexOutOfBoundsException
811      *         if the specified {@code index} is less than {@code 0} or
812      *         if {@code index + dst.writableBytes} is greater than
813      *            {@code this.capacity}
814      */
815     public abstract ByteBuf getBytes(int index, ByteBuf dst);
816 
817     /**
818      * Transfers this buffer's data to the specified destination starting at
819      * the specified absolute {@code index}.  This method is basically same
820      * with {@link #getBytes(int, ByteBuf, int, int)}, except that this
821      * method increases the {@code writerIndex} of the destination by the
822      * number of the transferred bytes while
823      * {@link #getBytes(int, ByteBuf, int, int)} does not.
824      * This method does not modify {@code readerIndex} or {@code writerIndex} of
825      * the source buffer (i.e. {@code this}).
826      *
827      * @param length the number of bytes to transfer
828      *
829      * @throws IndexOutOfBoundsException
830      *         if the specified {@code index} is less than {@code 0},
831      *         if {@code index + length} is greater than
832      *            {@code this.capacity}, or
833      *         if {@code length} is greater than {@code dst.writableBytes}
834      */
835     public abstract ByteBuf getBytes(int index, ByteBuf dst, int length);
836 
837     /**
838      * Transfers this buffer's data to the specified destination starting at
839      * the specified absolute {@code index}.
840      * This method does not modify {@code readerIndex} or {@code writerIndex}
841      * of both the source (i.e. {@code this}) and the destination.
842      *
843      * @param dstIndex the first index of the destination
844      * @param length   the number of bytes to transfer
845      *
846      * @throws IndexOutOfBoundsException
847      *         if the specified {@code index} is less than {@code 0},
848      *         if the specified {@code dstIndex} is less than {@code 0},
849      *         if {@code index + length} is greater than
850      *            {@code this.capacity}, or
851      *         if {@code dstIndex + length} is greater than
852      *            {@code dst.capacity}
853      */
854     public abstract ByteBuf getBytes(int index, ByteBuf dst, int dstIndex, int length);
855 
856     /**
857      * Transfers this buffer's data to the specified destination starting at
858      * the specified absolute {@code index}.
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      *         if {@code index + dst.length} is greater than
865      *            {@code this.capacity}
866      */
867     public abstract ByteBuf getBytes(int index, byte[] dst);
868 
869     /**
870      * Transfers this buffer's data to the specified destination starting at
871      * the specified absolute {@code index}.
872      * This method does not modify {@code readerIndex} or {@code writerIndex}
873      * of this buffer.
874      *
875      * @param dstIndex the first index of the destination
876      * @param length   the number of bytes to transfer
877      *
878      * @throws IndexOutOfBoundsException
879      *         if the specified {@code index} is less than {@code 0},
880      *         if the specified {@code dstIndex} is less than {@code 0},
881      *         if {@code index + length} is greater than
882      *            {@code this.capacity}, or
883      *         if {@code dstIndex + length} is greater than
884      *            {@code dst.length}
885      */
886     public abstract ByteBuf getBytes(int index, byte[] dst, int dstIndex, int length);
887 
888     /**
889      * Transfers this buffer's data to the specified destination starting at
890      * the specified absolute {@code index} until the destination's position
891      * reaches its limit.
892      * This method does not modify {@code readerIndex} or {@code writerIndex} of
893      * this buffer while the destination's {@code position} will be increased.
894      *
895      * @throws IndexOutOfBoundsException
896      *         if the specified {@code index} is less than {@code 0} or
897      *         if {@code index + dst.remaining()} is greater than
898      *            {@code this.capacity}
899      */
900     public abstract ByteBuf getBytes(int index, ByteBuffer dst);
901 
902     /**
903      * Transfers this buffer's data to the specified stream starting at the
904      * specified absolute {@code index}.
905      * This method does not modify {@code readerIndex} or {@code writerIndex} of
906      * this buffer.
907      *
908      * @param length the number of bytes to transfer
909      *
910      * @throws IndexOutOfBoundsException
911      *         if the specified {@code index} is less than {@code 0} or
912      *         if {@code index + length} is greater than
913      *            {@code this.capacity}
914      * @throws IOException
915      *         if the specified stream threw an exception during I/O
916      */
917     public abstract ByteBuf getBytes(int index, OutputStream out, int length) throws IOException;
918 
919     /**
920      * Transfers this buffer's data to the specified channel starting at the
921      * specified absolute {@code index}.
922      * This method does not modify {@code readerIndex} or {@code writerIndex} of
923      * this buffer.
924      *
925      * @param length the maximum number of bytes to transfer
926      *
927      * @return the actual number of bytes written out to the specified channel
928      *
929      * @throws IndexOutOfBoundsException
930      *         if the specified {@code index} is less than {@code 0} or
931      *         if {@code index + length} is greater than
932      *            {@code this.capacity}
933      * @throws IOException
934      *         if the specified channel threw an exception during I/O
935      */
936     public abstract int getBytes(int index, GatheringByteChannel out, int length) throws IOException;
937 
938     /**
939      * Transfers this buffer's data starting at the specified absolute {@code index}
940      * to the specified channel starting at the given file position.
941      * This method does not modify {@code readerIndex} or {@code writerIndex} of
942      * this buffer. This method does not modify the channel's position.
943      *
944      * @param position the file position at which the transfer is to begin
945      * @param length the maximum number of bytes to transfer
946      *
947      * @return the actual number of bytes written out to the specified channel
948      *
949      * @throws IndexOutOfBoundsException
950      *         if the specified {@code index} is less than {@code 0} or
951      *         if {@code index + length} is greater than
952      *            {@code this.capacity}
953      * @throws IOException
954      *         if the specified channel threw an exception during I/O
955      */
956     public abstract int getBytes(int index, FileChannel out, long position, int length) throws IOException;
957 
958     /**
959      * Gets a {@link CharSequence} with the given length at the given index.
960      *
961      * @param length the length to read
962      * @param charset that should be used
963      * @return the sequence
964      * @throws IndexOutOfBoundsException
965      *         if {@code length} is greater than {@code this.readableBytes}
966      */
967     public abstract CharSequence getCharSequence(int index, int length, Charset charset);
968 
969     /**
970      * Sets the specified boolean at the specified absolute {@code index} in this
971      * buffer.
972      * This method does not modify {@code readerIndex} or {@code writerIndex} of
973      * this buffer.
974      *
975      * @throws IndexOutOfBoundsException
976      *         if the specified {@code index} is less than {@code 0} or
977      *         {@code index + 1} is greater than {@code this.capacity}
978      */
979     public abstract ByteBuf setBoolean(int index, boolean value);
980 
981     /**
982      * Sets the specified byte at the specified absolute {@code index} in this
983      * buffer.  The 24 high-order bits of the specified value are ignored.
984      * This method does not modify {@code readerIndex} or {@code writerIndex} of
985      * this buffer.
986      *
987      * @throws IndexOutOfBoundsException
988      *         if the specified {@code index} is less than {@code 0} or
989      *         {@code index + 1} is greater than {@code this.capacity}
990      */
991     public abstract ByteBuf setByte(int index, int value);
992 
993     /**
994      * Sets the specified 16-bit short integer at the specified absolute
995      * {@code index} in this buffer.  The 16 high-order bits of the specified
996      * value are ignored.
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      *         {@code index + 2} is greater than {@code this.capacity}
1003      */
1004     public abstract ByteBuf setShort(int index, int value);
1005 
1006     /**
1007      * Sets the specified 16-bit short integer at the specified absolute
1008      * {@code index} in this buffer with the Little Endian Byte Order.
1009      * The 16 high-order bits of the specified value are ignored.
1010      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1011      * this buffer.
1012      *
1013      * @throws IndexOutOfBoundsException
1014      *         if the specified {@code index} is less than {@code 0} or
1015      *         {@code index + 2} is greater than {@code this.capacity}
1016      */
1017     public abstract ByteBuf setShortLE(int index, int value);
1018 
1019     /**
1020      * Sets the specified 24-bit medium integer at the specified absolute
1021      * {@code index} in this buffer.  Please note that the most significant
1022      * byte is ignored in the specified value.
1023      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1024      * this buffer.
1025      *
1026      * @throws IndexOutOfBoundsException
1027      *         if the specified {@code index} is less than {@code 0} or
1028      *         {@code index + 3} is greater than {@code this.capacity}
1029      */
1030     public abstract ByteBuf setMedium(int index, int value);
1031 
1032     /**
1033      * Sets the specified 24-bit medium integer at the specified absolute
1034      * {@code index} in this buffer in the Little Endian Byte Order.
1035      * Please note that the most significant byte is ignored in the
1036      * specified value.
1037      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1038      * this buffer.
1039      *
1040      * @throws IndexOutOfBoundsException
1041      *         if the specified {@code index} is less than {@code 0} or
1042      *         {@code index + 3} is greater than {@code this.capacity}
1043      */
1044     public abstract ByteBuf setMediumLE(int index, int value);
1045 
1046     /**
1047      * Sets the specified 32-bit integer at the specified absolute
1048      * {@code index} in this buffer.
1049      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1050      * this buffer.
1051      *
1052      * @throws IndexOutOfBoundsException
1053      *         if the specified {@code index} is less than {@code 0} or
1054      *         {@code index + 4} is greater than {@code this.capacity}
1055      */
1056     public abstract ByteBuf setInt(int index, int value);
1057 
1058     /**
1059      * Sets the specified 32-bit integer at the specified absolute
1060      * {@code index} in this buffer with Little Endian byte order
1061      * .
1062      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1063      * this buffer.
1064      *
1065      * @throws IndexOutOfBoundsException
1066      *         if the specified {@code index} is less than {@code 0} or
1067      *         {@code index + 4} is greater than {@code this.capacity}
1068      */
1069     public abstract ByteBuf setIntLE(int index, int value);
1070 
1071     /**
1072      * Sets the specified 64-bit long integer at the specified absolute
1073      * {@code index} in this buffer.
1074      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1075      * this buffer.
1076      *
1077      * @throws IndexOutOfBoundsException
1078      *         if the specified {@code index} is less than {@code 0} or
1079      *         {@code index + 8} is greater than {@code this.capacity}
1080      */
1081     public abstract ByteBuf setLong(int index, long value);
1082 
1083     /**
1084      * Sets the specified 64-bit long integer at the specified absolute
1085      * {@code index} in this buffer in Little Endian Byte Order.
1086      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1087      * this buffer.
1088      *
1089      * @throws IndexOutOfBoundsException
1090      *         if the specified {@code index} is less than {@code 0} or
1091      *         {@code index + 8} is greater than {@code this.capacity}
1092      */
1093     public abstract ByteBuf setLongLE(int index, long value);
1094 
1095     /**
1096      * Sets the specified 2-byte UTF-16 character at the specified absolute
1097      * {@code index} in this buffer.
1098      * The 16 high-order bits of the specified value are ignored.
1099      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1100      * this buffer.
1101      *
1102      * @throws IndexOutOfBoundsException
1103      *         if the specified {@code index} is less than {@code 0} or
1104      *         {@code index + 2} is greater than {@code this.capacity}
1105      */
1106     public abstract ByteBuf setChar(int index, int value);
1107 
1108     /**
1109      * Sets the specified 32-bit floating-point number at the specified
1110      * absolute {@code index} in this buffer.
1111      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1112      * this buffer.
1113      *
1114      * @throws IndexOutOfBoundsException
1115      *         if the specified {@code index} is less than {@code 0} or
1116      *         {@code index + 4} is greater than {@code this.capacity}
1117      */
1118     public abstract ByteBuf setFloat(int index, float value);
1119 
1120     /**
1121      * Sets the specified 32-bit floating-point number at the specified
1122      * absolute {@code index} in this buffer in Little Endian Byte Order.
1123      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1124      * this buffer.
1125      *
1126      * @throws IndexOutOfBoundsException
1127      *         if the specified {@code index} is less than {@code 0} or
1128      *         {@code index + 4} is greater than {@code this.capacity}
1129      */
1130     public ByteBuf setFloatLE(int index, float value) {
1131         return setIntLE(index, Float.floatToRawIntBits(value));
1132     }
1133 
1134     /**
1135      * Sets the specified 64-bit floating-point number at the specified
1136      * absolute {@code index} in this buffer.
1137      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1138      * this buffer.
1139      *
1140      * @throws IndexOutOfBoundsException
1141      *         if the specified {@code index} is less than {@code 0} or
1142      *         {@code index + 8} is greater than {@code this.capacity}
1143      */
1144     public abstract ByteBuf setDouble(int index, double value);
1145 
1146     /**
1147      * Sets the specified 64-bit floating-point number at the specified
1148      * absolute {@code index} in this buffer in Little Endian Byte Order.
1149      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1150      * this buffer.
1151      *
1152      * @throws IndexOutOfBoundsException
1153      *         if the specified {@code index} is less than {@code 0} or
1154      *         {@code index + 8} is greater than {@code this.capacity}
1155      */
1156     public ByteBuf setDoubleLE(int index, double value) {
1157         return setLongLE(index, Double.doubleToRawLongBits(value));
1158     }
1159 
1160     /**
1161      * Transfers the specified source buffer's data to this buffer starting at
1162      * the specified absolute {@code index} until the source buffer becomes
1163      * unreadable.  This method is basically same with
1164      * {@link #setBytes(int, ByteBuf, int, int)}, except that this
1165      * method increases the {@code readerIndex} of the source buffer by
1166      * the number of the transferred bytes while
1167      * {@link #setBytes(int, ByteBuf, int, int)} does not.
1168      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1169      * the source buffer (i.e. {@code this}).
1170      *
1171      * @throws IndexOutOfBoundsException
1172      *         if the specified {@code index} is less than {@code 0} or
1173      *         if {@code index + src.readableBytes} is greater than
1174      *            {@code this.capacity}
1175      */
1176     public abstract ByteBuf setBytes(int index, ByteBuf src);
1177 
1178     /**
1179      * Transfers the specified source buffer's data to this buffer starting at
1180      * the specified absolute {@code index}.  This method is basically same
1181      * with {@link #setBytes(int, ByteBuf, int, int)}, except that this
1182      * method increases the {@code readerIndex} of the source buffer by
1183      * the number of the transferred bytes while
1184      * {@link #setBytes(int, ByteBuf, int, int)} does not.
1185      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1186      * the source buffer (i.e. {@code this}).
1187      *
1188      * @param length the number of bytes to transfer
1189      *
1190      * @throws IndexOutOfBoundsException
1191      *         if the specified {@code index} is less than {@code 0},
1192      *         if {@code index + length} is greater than
1193      *            {@code this.capacity}, or
1194      *         if {@code length} is greater than {@code src.readableBytes}
1195      */
1196     public abstract ByteBuf setBytes(int index, ByteBuf src, int length);
1197 
1198     /**
1199      * Transfers the specified source buffer's data to this buffer starting at
1200      * the specified absolute {@code index}.
1201      * This method does not modify {@code readerIndex} or {@code writerIndex}
1202      * of both the source (i.e. {@code this}) and the destination.
1203      *
1204      * @param srcIndex the first index of the source
1205      * @param length   the number of bytes to transfer
1206      *
1207      * @throws IndexOutOfBoundsException
1208      *         if the specified {@code index} is less than {@code 0},
1209      *         if the specified {@code srcIndex} is less than {@code 0},
1210      *         if {@code index + length} is greater than
1211      *            {@code this.capacity}, or
1212      *         if {@code srcIndex + length} is greater than
1213      *            {@code src.capacity}
1214      */
1215     public abstract ByteBuf setBytes(int index, ByteBuf src, int srcIndex, int length);
1216 
1217     /**
1218      * Transfers the specified source array's data to this buffer starting at
1219      * the specified absolute {@code index}.
1220      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1221      * this buffer.
1222      *
1223      * @throws IndexOutOfBoundsException
1224      *         if the specified {@code index} is less than {@code 0} or
1225      *         if {@code index + src.length} is greater than
1226      *            {@code this.capacity}
1227      */
1228     public abstract ByteBuf setBytes(int index, byte[] src);
1229 
1230     /**
1231      * Transfers the specified source array's data to this buffer starting at
1232      * the specified absolute {@code index}.
1233      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1234      * this buffer.
1235      *
1236      * @throws IndexOutOfBoundsException
1237      *         if the specified {@code index} is less than {@code 0},
1238      *         if the specified {@code srcIndex} is less than {@code 0},
1239      *         if {@code index + length} is greater than
1240      *            {@code this.capacity}, or
1241      *         if {@code srcIndex + length} is greater than {@code src.length}
1242      */
1243     public abstract ByteBuf setBytes(int index, byte[] src, int srcIndex, int length);
1244 
1245     /**
1246      * Transfers the specified source buffer's data to this buffer starting at
1247      * the specified absolute {@code index} until the source buffer's position
1248      * reaches its limit.
1249      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1250      * this buffer.
1251      *
1252      * @throws IndexOutOfBoundsException
1253      *         if the specified {@code index} is less than {@code 0} or
1254      *         if {@code index + src.remaining()} is greater than
1255      *            {@code this.capacity}
1256      */
1257     public abstract ByteBuf setBytes(int index, ByteBuffer src);
1258 
1259     /**
1260      * Transfers the content of the specified source stream to this buffer
1261      * starting at the specified absolute {@code index}.
1262      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1263      * this buffer.
1264      *
1265      * @param length the number of bytes to transfer
1266      *
1267      * @return the actual number of bytes read in from the specified channel.
1268      *         {@code -1} if the specified channel is closed.
1269      *
1270      * @throws IndexOutOfBoundsException
1271      *         if the specified {@code index} is less than {@code 0} or
1272      *         if {@code index + length} is greater than {@code this.capacity}
1273      * @throws IOException
1274      *         if the specified stream threw an exception during I/O
1275      */
1276     public abstract int setBytes(int index, InputStream in, int length) throws IOException;
1277 
1278     /**
1279      * Transfers the content of the specified source channel to this buffer
1280      * starting at the specified absolute {@code index}.
1281      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1282      * this buffer.
1283      *
1284      * @param length the maximum number of bytes to transfer
1285      *
1286      * @return the actual number of bytes read in from the specified channel.
1287      *         {@code -1} if the specified channel is closed.
1288      *
1289      * @throws IndexOutOfBoundsException
1290      *         if the specified {@code index} is less than {@code 0} or
1291      *         if {@code index + length} is greater than {@code this.capacity}
1292      * @throws IOException
1293      *         if the specified channel threw an exception during I/O
1294      */
1295     public abstract int setBytes(int index, ScatteringByteChannel in, int length) throws IOException;
1296 
1297     /**
1298      * Transfers the content of the specified source channel starting at the given file position
1299      * to this buffer starting at the specified absolute {@code index}.
1300      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1301      * this buffer. This method does not modify the channel's position.
1302      *
1303      * @param position the file position at which the transfer is to begin
1304      * @param length the maximum number of bytes to transfer
1305      *
1306      * @return the actual number of bytes read in from the specified channel.
1307      *         {@code -1} if the specified channel is closed.
1308      *
1309      * @throws IndexOutOfBoundsException
1310      *         if the specified {@code index} is less than {@code 0} or
1311      *         if {@code index + length} is greater than {@code this.capacity}
1312      * @throws IOException
1313      *         if the specified channel threw an exception during I/O
1314      */
1315     public abstract int setBytes(int index, FileChannel in, long position, int length) throws IOException;
1316 
1317     /**
1318      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the specified
1319      * absolute {@code index}.
1320      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1321      * this buffer.
1322      *
1323      * @param length the number of <tt>NUL</tt>s to write to the buffer
1324      *
1325      * @throws IndexOutOfBoundsException
1326      *         if the specified {@code index} is less than {@code 0} or
1327      *         if {@code index + length} is greater than {@code this.capacity}
1328      */
1329     public abstract ByteBuf setZero(int index, int length);
1330 
1331     /**
1332      * Writes the specified {@link CharSequence} at the current {@code writerIndex} and increases
1333      * the {@code writerIndex} by the written bytes.
1334      *
1335      * @param index on which the sequence should be written
1336      * @param sequence to write
1337      * @param charset that should be used.
1338      * @return the written number of bytes.
1339      * @throws IndexOutOfBoundsException
1340      *         if {@code this.writableBytes} is not large enough to write the whole sequence
1341      */
1342     public abstract int setCharSequence(int index, CharSequence sequence, Charset charset);
1343 
1344     /**
1345      * Gets a boolean at the current {@code readerIndex} and increases
1346      * the {@code readerIndex} by {@code 1} in this buffer.
1347      *
1348      * @throws IndexOutOfBoundsException
1349      *         if {@code this.readableBytes} is less than {@code 1}
1350      */
1351     public abstract boolean readBoolean();
1352 
1353     /**
1354      * Gets a byte at the current {@code readerIndex} and increases
1355      * the {@code readerIndex} by {@code 1} in this buffer.
1356      *
1357      * @throws IndexOutOfBoundsException
1358      *         if {@code this.readableBytes} is less than {@code 1}
1359      */
1360     public abstract byte  readByte();
1361 
1362     /**
1363      * Gets an unsigned byte at the current {@code readerIndex} and increases
1364      * the {@code readerIndex} by {@code 1} in this buffer.
1365      *
1366      * @throws IndexOutOfBoundsException
1367      *         if {@code this.readableBytes} is less than {@code 1}
1368      */
1369     public abstract short readUnsignedByte();
1370 
1371     /**
1372      * Gets a 16-bit short integer at the current {@code readerIndex}
1373      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1374      *
1375      * @throws IndexOutOfBoundsException
1376      *         if {@code this.readableBytes} is less than {@code 2}
1377      */
1378     public abstract short readShort();
1379 
1380     /**
1381      * Gets a 16-bit short integer at the current {@code readerIndex}
1382      * in the Little Endian Byte Order and increases the {@code readerIndex}
1383      * by {@code 2} in this buffer.
1384      *
1385      * @throws IndexOutOfBoundsException
1386      *         if {@code this.readableBytes} is less than {@code 2}
1387      */
1388     public abstract short readShortLE();
1389 
1390     /**
1391      * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1392      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1393      *
1394      * @throws IndexOutOfBoundsException
1395      *         if {@code this.readableBytes} is less than {@code 2}
1396      */
1397     public abstract int   readUnsignedShort();
1398 
1399     /**
1400      * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1401      * in the Little Endian Byte Order and increases the {@code readerIndex}
1402      * by {@code 2} in this buffer.
1403      *
1404      * @throws IndexOutOfBoundsException
1405      *         if {@code this.readableBytes} is less than {@code 2}
1406      */
1407     public abstract int   readUnsignedShortLE();
1408 
1409     /**
1410      * Gets a 24-bit medium integer at the current {@code readerIndex}
1411      * and increases the {@code readerIndex} by {@code 3} in this buffer.
1412      *
1413      * @throws IndexOutOfBoundsException
1414      *         if {@code this.readableBytes} is less than {@code 3}
1415      */
1416     public abstract int   readMedium();
1417 
1418     /**
1419      * Gets a 24-bit medium integer at the current {@code readerIndex}
1420      * in the Little Endian Byte Order and increases the
1421      * {@code readerIndex} by {@code 3} in this buffer.
1422      *
1423      * @throws IndexOutOfBoundsException
1424      *         if {@code this.readableBytes} is less than {@code 3}
1425      */
1426     public abstract int   readMediumLE();
1427 
1428     /**
1429      * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1430      * and increases the {@code readerIndex} by {@code 3} in this buffer.
1431      *
1432      * @throws IndexOutOfBoundsException
1433      *         if {@code this.readableBytes} is less than {@code 3}
1434      */
1435     public abstract int   readUnsignedMedium();
1436 
1437     /**
1438      * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1439      * in the Little Endian Byte Order and increases the {@code readerIndex}
1440      * by {@code 3} in this buffer.
1441      *
1442      * @throws IndexOutOfBoundsException
1443      *         if {@code this.readableBytes} is less than {@code 3}
1444      */
1445     public abstract int   readUnsignedMediumLE();
1446 
1447     /**
1448      * Gets a 32-bit integer at the current {@code readerIndex}
1449      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1450      *
1451      * @throws IndexOutOfBoundsException
1452      *         if {@code this.readableBytes} is less than {@code 4}
1453      */
1454     public abstract int   readInt();
1455 
1456     /**
1457      * Gets a 32-bit integer at the current {@code readerIndex}
1458      * in the Little Endian Byte Order and increases the {@code readerIndex}
1459      * by {@code 4} in this buffer.
1460      *
1461      * @throws IndexOutOfBoundsException
1462      *         if {@code this.readableBytes} is less than {@code 4}
1463      */
1464     public abstract int   readIntLE();
1465 
1466     /**
1467      * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1468      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1469      *
1470      * @throws IndexOutOfBoundsException
1471      *         if {@code this.readableBytes} is less than {@code 4}
1472      */
1473     public abstract long  readUnsignedInt();
1474 
1475     /**
1476      * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1477      * in the Little Endian Byte Order and increases the {@code readerIndex}
1478      * by {@code 4} in this buffer.
1479      *
1480      * @throws IndexOutOfBoundsException
1481      *         if {@code this.readableBytes} is less than {@code 4}
1482      */
1483     public abstract long  readUnsignedIntLE();
1484 
1485     /**
1486      * Gets a 64-bit integer at the current {@code readerIndex}
1487      * and increases the {@code readerIndex} by {@code 8} in this buffer.
1488      *
1489      * @throws IndexOutOfBoundsException
1490      *         if {@code this.readableBytes} is less than {@code 8}
1491      */
1492     public abstract long  readLong();
1493 
1494     /**
1495      * Gets a 64-bit integer at the current {@code readerIndex}
1496      * in the Little Endian Byte Order and increases the {@code readerIndex}
1497      * by {@code 8} in this buffer.
1498      *
1499      * @throws IndexOutOfBoundsException
1500      *         if {@code this.readableBytes} is less than {@code 8}
1501      */
1502     public abstract long  readLongLE();
1503 
1504     /**
1505      * Gets a 2-byte UTF-16 character at the current {@code readerIndex}
1506      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1507      *
1508      * @throws IndexOutOfBoundsException
1509      *         if {@code this.readableBytes} is less than {@code 2}
1510      */
1511     public abstract char  readChar();
1512 
1513     /**
1514      * Gets a 32-bit floating point number at the current {@code readerIndex}
1515      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1516      *
1517      * @throws IndexOutOfBoundsException
1518      *         if {@code this.readableBytes} is less than {@code 4}
1519      */
1520     public abstract float readFloat();
1521 
1522     /**
1523      * Gets a 32-bit floating point number at the current {@code readerIndex}
1524      * in Little Endian Byte Order and increases the {@code readerIndex}
1525      * by {@code 4} in this buffer.
1526      *
1527      * @throws IndexOutOfBoundsException
1528      *         if {@code this.readableBytes} is less than {@code 4}
1529      */
1530     public float readFloatLE() {
1531         return Float.intBitsToFloat(readIntLE());
1532     }
1533 
1534     /**
1535      * Gets a 64-bit floating point number at the current {@code readerIndex}
1536      * and increases the {@code readerIndex} by {@code 8} in this buffer.
1537      *
1538      * @throws IndexOutOfBoundsException
1539      *         if {@code this.readableBytes} is less than {@code 8}
1540      */
1541     public abstract double readDouble();
1542 
1543     /**
1544      * Gets a 64-bit floating point number at the current {@code readerIndex}
1545      * in Little Endian Byte Order and increases the {@code readerIndex}
1546      * by {@code 8} in this buffer.
1547      *
1548      * @throws IndexOutOfBoundsException
1549      *         if {@code this.readableBytes} is less than {@code 8}
1550      */
1551     public double readDoubleLE() {
1552         return Double.longBitsToDouble(readLongLE());
1553     }
1554 
1555     /**
1556      * Transfers this buffer's data to a newly created buffer starting at
1557      * the current {@code readerIndex} and increases the {@code readerIndex}
1558      * by the number of the transferred bytes (= {@code length}).
1559      * The returned buffer's {@code readerIndex} and {@code writerIndex} are
1560      * {@code 0} and {@code length} respectively.
1561      *
1562      * @param length the number of bytes to transfer
1563      *
1564      * @return the newly created buffer which contains the transferred bytes
1565      *
1566      * @throws IndexOutOfBoundsException
1567      *         if {@code length} is greater than {@code this.readableBytes}
1568      */
1569     public abstract ByteBuf readBytes(int length);
1570 
1571     /**
1572      * Returns a new slice of this buffer's sub-region starting at the current
1573      * {@code readerIndex} and increases the {@code readerIndex} by the size
1574      * of the new slice (= {@code length}).
1575      * <p>
1576      * Also be aware that this method will NOT call {@link #retain()} and so the
1577      * reference count will NOT be increased.
1578      *
1579      * @param length the size of the new slice
1580      *
1581      * @return the newly created slice
1582      *
1583      * @throws IndexOutOfBoundsException
1584      *         if {@code length} is greater than {@code this.readableBytes}
1585      */
1586     public abstract ByteBuf readSlice(int length);
1587 
1588     /**
1589      * Returns a new retained slice of this buffer's sub-region starting at the current
1590      * {@code readerIndex} and increases the {@code readerIndex} by the size
1591      * of the new slice (= {@code length}).
1592      * <p>
1593      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #readSlice(int)}.
1594      * This method behaves similarly to {@code readSlice(...).retain()} except that this method may return
1595      * a buffer implementation that produces less garbage.
1596      *
1597      * @param length the size of the new slice
1598      *
1599      * @return the newly created slice
1600      *
1601      * @throws IndexOutOfBoundsException
1602      *         if {@code length} is greater than {@code this.readableBytes}
1603      */
1604     public abstract ByteBuf readRetainedSlice(int length);
1605 
1606     /**
1607      * Transfers this buffer's data to the specified destination starting at
1608      * the current {@code readerIndex} until the destination becomes
1609      * non-writable, and increases the {@code readerIndex} by the number of the
1610      * transferred bytes.  This method is basically same with
1611      * {@link #readBytes(ByteBuf, int, int)}, except that this method
1612      * increases the {@code writerIndex} of the destination by the number of
1613      * the transferred bytes while {@link #readBytes(ByteBuf, int, int)}
1614      * does not.
1615      *
1616      * @throws IndexOutOfBoundsException
1617      *         if {@code dst.writableBytes} is greater than
1618      *            {@code this.readableBytes}
1619      */
1620     public abstract ByteBuf readBytes(ByteBuf dst);
1621 
1622     /**
1623      * Transfers this buffer's data to the specified destination starting at
1624      * the current {@code readerIndex} and increases the {@code readerIndex}
1625      * by the number of the transferred bytes (= {@code length}).  This method
1626      * is basically same with {@link #readBytes(ByteBuf, int, int)},
1627      * except that this method increases the {@code writerIndex} of the
1628      * destination by the number of the transferred bytes (= {@code length})
1629      * while {@link #readBytes(ByteBuf, int, int)} does not.
1630      *
1631      * @throws IndexOutOfBoundsException
1632      *         if {@code length} is greater than {@code this.readableBytes} or
1633      *         if {@code length} is greater than {@code dst.writableBytes}
1634      */
1635     public abstract ByteBuf readBytes(ByteBuf dst, int length);
1636 
1637     /**
1638      * Transfers this buffer's data to the specified destination starting at
1639      * the current {@code readerIndex} and increases the {@code readerIndex}
1640      * by the number of the transferred bytes (= {@code length}).
1641      *
1642      * @param dstIndex the first index of the destination
1643      * @param length   the number of bytes to transfer
1644      *
1645      * @throws IndexOutOfBoundsException
1646      *         if the specified {@code dstIndex} is less than {@code 0},
1647      *         if {@code length} is greater than {@code this.readableBytes}, or
1648      *         if {@code dstIndex + length} is greater than
1649      *            {@code dst.capacity}
1650      */
1651     public abstract ByteBuf readBytes(ByteBuf dst, int dstIndex, int length);
1652 
1653     /**
1654      * Transfers this buffer's data to the specified destination starting at
1655      * the current {@code readerIndex} and increases the {@code readerIndex}
1656      * by the number of the transferred bytes (= {@code dst.length}).
1657      *
1658      * @throws IndexOutOfBoundsException
1659      *         if {@code dst.length} is greater than {@code this.readableBytes}
1660      */
1661     public abstract ByteBuf readBytes(byte[] dst);
1662 
1663     /**
1664      * Transfers this buffer's data to the specified destination starting at
1665      * the current {@code readerIndex} and increases the {@code readerIndex}
1666      * by the number of the transferred bytes (= {@code length}).
1667      *
1668      * @param dstIndex the first index of the destination
1669      * @param length   the number of bytes to transfer
1670      *
1671      * @throws IndexOutOfBoundsException
1672      *         if the specified {@code dstIndex} is less than {@code 0},
1673      *         if {@code length} is greater than {@code this.readableBytes}, or
1674      *         if {@code dstIndex + length} is greater than {@code dst.length}
1675      */
1676     public abstract ByteBuf readBytes(byte[] dst, int dstIndex, int length);
1677 
1678     /**
1679      * Transfers this buffer's data to the specified destination starting at
1680      * the current {@code readerIndex} until the destination's position
1681      * reaches its limit, and increases the {@code readerIndex} by the
1682      * number of the transferred bytes.
1683      *
1684      * @throws IndexOutOfBoundsException
1685      *         if {@code dst.remaining()} is greater than
1686      *            {@code this.readableBytes}
1687      */
1688     public abstract ByteBuf readBytes(ByteBuffer dst);
1689 
1690     /**
1691      * Transfers this buffer's data to the specified stream starting at the
1692      * current {@code readerIndex}.
1693      *
1694      * @param length the number of bytes to transfer
1695      *
1696      * @throws IndexOutOfBoundsException
1697      *         if {@code length} is greater than {@code this.readableBytes}
1698      * @throws IOException
1699      *         if the specified stream threw an exception during I/O
1700      */
1701     public abstract ByteBuf readBytes(OutputStream out, int length) throws IOException;
1702 
1703     /**
1704      * Transfers this buffer's data to the specified stream starting at the
1705      * current {@code readerIndex}.
1706      *
1707      * @param length the maximum number of bytes to transfer
1708      *
1709      * @return the actual number of bytes written out to the specified channel
1710      *
1711      * @throws IndexOutOfBoundsException
1712      *         if {@code length} is greater than {@code this.readableBytes}
1713      * @throws IOException
1714      *         if the specified channel threw an exception during I/O
1715      */
1716     public abstract int readBytes(GatheringByteChannel out, int length) throws IOException;
1717 
1718     /**
1719      * Gets a {@link CharSequence} with the given length at the current {@code readerIndex}
1720      * and increases the {@code readerIndex} by the given length.
1721      *
1722      * @param length the length to read
1723      * @param charset that should be used
1724      * @return the sequence
1725      * @throws IndexOutOfBoundsException
1726      *         if {@code length} is greater than {@code this.readableBytes}
1727      */
1728     public abstract CharSequence readCharSequence(int length, Charset charset);
1729 
1730     /**
1731      * Transfers this buffer's data starting at the current {@code readerIndex}
1732      * to the specified channel starting at the given file position.
1733      * This method does not modify the channel's position.
1734      *
1735      * @param position the file position at which the transfer is to begin
1736      * @param length the maximum number of bytes to transfer
1737      *
1738      * @return the actual number of bytes written out to the specified channel
1739      *
1740      * @throws IndexOutOfBoundsException
1741      *         if {@code length} is greater than {@code this.readableBytes}
1742      * @throws IOException
1743      *         if the specified channel threw an exception during I/O
1744      */
1745     public abstract int readBytes(FileChannel out, long position, int length) throws IOException;
1746 
1747     /**
1748      * Increases the current {@code readerIndex} by the specified
1749      * {@code length} in this buffer.
1750      *
1751      * @throws IndexOutOfBoundsException
1752      *         if {@code length} is greater than {@code this.readableBytes}
1753      */
1754     public abstract ByteBuf skipBytes(int length);
1755 
1756     /**
1757      * Sets the specified boolean at the current {@code writerIndex}
1758      * and increases the {@code writerIndex} by {@code 1} in this buffer.
1759      *
1760      * @throws IndexOutOfBoundsException
1761      *         if {@code this.writableBytes} is less than {@code 1}
1762      */
1763     public abstract ByteBuf writeBoolean(boolean value);
1764 
1765     /**
1766      * Sets the specified byte at the current {@code writerIndex}
1767      * and increases the {@code writerIndex} by {@code 1} in this buffer.
1768      * The 24 high-order bits of the specified value are ignored.
1769      *
1770      * @throws IndexOutOfBoundsException
1771      *         if {@code this.writableBytes} is less than {@code 1}
1772      */
1773     public abstract ByteBuf writeByte(int value);
1774 
1775     /**
1776      * Sets the specified 16-bit short integer at the current
1777      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1778      * in this buffer.  The 16 high-order bits of the specified value are ignored.
1779      *
1780      * @throws IndexOutOfBoundsException
1781      *         if {@code this.writableBytes} is less than {@code 2}
1782      */
1783     public abstract ByteBuf writeShort(int value);
1784 
1785     /**
1786      * Sets the specified 16-bit short integer in the Little Endian Byte
1787      * Order at the current {@code writerIndex} and increases the
1788      * {@code writerIndex} by {@code 2} in this buffer.
1789      * The 16 high-order bits of the specified value are ignored.
1790      *
1791      * @throws IndexOutOfBoundsException
1792      *         if {@code this.writableBytes} is less than {@code 2}
1793      */
1794     public abstract ByteBuf writeShortLE(int value);
1795 
1796     /**
1797      * Sets the specified 24-bit medium integer at the current
1798      * {@code writerIndex} and increases the {@code writerIndex} by {@code 3}
1799      * in this buffer.
1800      *
1801      * @throws IndexOutOfBoundsException
1802      *         if {@code this.writableBytes} is less than {@code 3}
1803      */
1804     public abstract ByteBuf writeMedium(int value);
1805 
1806     /**
1807      * Sets the specified 24-bit medium integer at the current
1808      * {@code writerIndex} in the Little Endian Byte Order and
1809      * increases the {@code writerIndex} by {@code 3} in this
1810      * buffer.
1811      *
1812      * @throws IndexOutOfBoundsException
1813      *         if {@code this.writableBytes} is less than {@code 3}
1814      */
1815     public abstract ByteBuf writeMediumLE(int value);
1816 
1817     /**
1818      * Sets the specified 32-bit integer at the current {@code writerIndex}
1819      * and increases the {@code writerIndex} by {@code 4} in this buffer.
1820      *
1821      * @throws IndexOutOfBoundsException
1822      *         if {@code this.writableBytes} is less than {@code 4}
1823      */
1824     public abstract ByteBuf writeInt(int value);
1825 
1826     /**
1827      * Sets the specified 32-bit integer at the current {@code writerIndex}
1828      * in the Little Endian Byte Order and increases the {@code writerIndex}
1829      * by {@code 4} in this buffer.
1830      *
1831      * @throws IndexOutOfBoundsException
1832      *         if {@code this.writableBytes} is less than {@code 4}
1833      */
1834     public abstract ByteBuf writeIntLE(int value);
1835 
1836     /**
1837      * Sets the specified 64-bit long integer at the current
1838      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1839      * in this buffer.
1840      *
1841      * @throws IndexOutOfBoundsException
1842      *         if {@code this.writableBytes} is less than {@code 8}
1843      */
1844     public abstract ByteBuf writeLong(long value);
1845 
1846     /**
1847      * Sets the specified 64-bit long integer at the current
1848      * {@code writerIndex} in the Little Endian Byte Order and
1849      * increases the {@code writerIndex} by {@code 8}
1850      * in this buffer.
1851      *
1852      * @throws IndexOutOfBoundsException
1853      *         if {@code this.writableBytes} is less than {@code 8}
1854      */
1855     public abstract ByteBuf writeLongLE(long value);
1856 
1857     /**
1858      * Sets the specified 2-byte UTF-16 character at the current
1859      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1860      * in this buffer.  The 16 high-order bits of the specified value are ignored.
1861      *
1862      * @throws IndexOutOfBoundsException
1863      *         if {@code this.writableBytes} is less than {@code 2}
1864      */
1865     public abstract ByteBuf writeChar(int value);
1866 
1867     /**
1868      * Sets the specified 32-bit floating point number at the current
1869      * {@code writerIndex} and increases the {@code writerIndex} by {@code 4}
1870      * in this buffer.
1871      *
1872      * @throws IndexOutOfBoundsException
1873      *         if {@code this.writableBytes} is less than {@code 4}
1874      */
1875     public abstract ByteBuf writeFloat(float value);
1876 
1877     /**
1878      * Sets the specified 32-bit floating point number at the current
1879      * {@code writerIndex} in Little Endian Byte Order and increases
1880      * the {@code writerIndex} by {@code 4} in this buffer.
1881      *
1882      * @throws IndexOutOfBoundsException
1883      *         if {@code this.writableBytes} is less than {@code 4}
1884      */
1885     public ByteBuf writeFloatLE(float value) {
1886         return writeIntLE(Float.floatToRawIntBits(value));
1887     }
1888 
1889     /**
1890      * Sets the specified 64-bit floating point number at the current
1891      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1892      * in this buffer.
1893      *
1894      * @throws IndexOutOfBoundsException
1895      *         if {@code this.writableBytes} is less than {@code 8}
1896      */
1897     public abstract ByteBuf writeDouble(double value);
1898 
1899     /**
1900      * Sets the specified 64-bit floating point number at the current
1901      * {@code writerIndex} in Little Endian Byte Order and increases
1902      * the {@code writerIndex} by {@code 8} in this buffer.
1903      *
1904      * @throws IndexOutOfBoundsException
1905      *         if {@code this.writableBytes} is less than {@code 8}
1906      */
1907     public ByteBuf writeDoubleLE(double value) {
1908         return writeLongLE(Double.doubleToRawLongBits(value));
1909     }
1910 
1911     /**
1912      * Transfers the specified source buffer's data to this buffer starting at
1913      * the current {@code writerIndex} until the source buffer becomes
1914      * unreadable, and increases the {@code writerIndex} by the number of
1915      * the transferred bytes.  This method is basically same with
1916      * {@link #writeBytes(ByteBuf, int, int)}, except that this method
1917      * increases the {@code readerIndex} of the source buffer by the number of
1918      * the transferred bytes while {@link #writeBytes(ByteBuf, int, int)}
1919      * does not.
1920      *
1921      * @throws IndexOutOfBoundsException
1922      *         if {@code src.readableBytes} is greater than
1923      *            {@code this.writableBytes}
1924      */
1925     public abstract ByteBuf writeBytes(ByteBuf src);
1926 
1927     /**
1928      * Transfers the specified source buffer's data to this buffer starting at
1929      * the current {@code writerIndex} and increases the {@code writerIndex}
1930      * by the number of the transferred bytes (= {@code length}).  This method
1931      * is basically same with {@link #writeBytes(ByteBuf, int, int)},
1932      * except that this method increases the {@code readerIndex} of the source
1933      * buffer by the number of the transferred bytes (= {@code length}) while
1934      * {@link #writeBytes(ByteBuf, int, int)} does not.
1935      *
1936      * @param length the number of bytes to transfer
1937      *
1938      * @throws IndexOutOfBoundsException
1939      *         if {@code length} is greater than {@code this.writableBytes} or
1940      *         if {@code length} is greater then {@code src.readableBytes}
1941      */
1942     public abstract ByteBuf writeBytes(ByteBuf src, int length);
1943 
1944     /**
1945      * Transfers the specified source buffer's data to this buffer starting at
1946      * the current {@code writerIndex} and increases the {@code writerIndex}
1947      * by the number of the transferred bytes (= {@code length}).
1948      *
1949      * @param srcIndex the first index of the source
1950      * @param length   the number of bytes to transfer
1951      *
1952      * @throws IndexOutOfBoundsException
1953      *         if the specified {@code srcIndex} is less than {@code 0},
1954      *         if {@code srcIndex + length} is greater than
1955      *            {@code src.capacity}, or
1956      *         if {@code length} is greater than {@code this.writableBytes}
1957      */
1958     public abstract ByteBuf writeBytes(ByteBuf src, int srcIndex, int length);
1959 
1960     /**
1961      * Transfers the specified source array's data to this buffer starting at
1962      * the current {@code writerIndex} and increases the {@code writerIndex}
1963      * by the number of the transferred bytes (= {@code src.length}).
1964      *
1965      * @throws IndexOutOfBoundsException
1966      *         if {@code src.length} is greater than {@code this.writableBytes}
1967      */
1968     public abstract ByteBuf writeBytes(byte[] src);
1969 
1970     /**
1971      * Transfers the specified source array's data to this buffer starting at
1972      * the current {@code writerIndex} and increases the {@code writerIndex}
1973      * by the number of the transferred bytes (= {@code length}).
1974      *
1975      * @param srcIndex the first index of the source
1976      * @param length   the number of bytes to transfer
1977      *
1978      * @throws IndexOutOfBoundsException
1979      *         if the specified {@code srcIndex} is less than {@code 0},
1980      *         if {@code srcIndex + length} is greater than
1981      *            {@code src.length}, or
1982      *         if {@code length} is greater than {@code this.writableBytes}
1983      */
1984     public abstract ByteBuf writeBytes(byte[] src, int srcIndex, int length);
1985 
1986     /**
1987      * Transfers the specified source buffer's data to this buffer starting at
1988      * the current {@code writerIndex} until the source buffer's position
1989      * reaches its limit, and increases the {@code writerIndex} by the
1990      * number of the transferred bytes.
1991      *
1992      * @throws IndexOutOfBoundsException
1993      *         if {@code src.remaining()} is greater than
1994      *            {@code this.writableBytes}
1995      */
1996     public abstract ByteBuf writeBytes(ByteBuffer src);
1997 
1998     /**
1999      * Transfers the content of the specified stream to this buffer
2000      * starting at the current {@code writerIndex} and increases the
2001      * {@code writerIndex} by the number of the transferred bytes.
2002      *
2003      * @param length the number of bytes to transfer
2004      *
2005      * @return the actual number of bytes read in from the specified stream
2006      *
2007      * @throws IndexOutOfBoundsException
2008      *         if {@code length} is greater than {@code this.writableBytes}
2009      * @throws IOException
2010      *         if the specified stream threw an exception during I/O
2011      */
2012     public abstract int  writeBytes(InputStream in, int length) throws IOException;
2013 
2014     /**
2015      * Transfers the content of the specified channel to this buffer
2016      * starting at the current {@code writerIndex} and increases the
2017      * {@code writerIndex} by the number of the transferred bytes.
2018      *
2019      * @param length the maximum number of bytes to transfer
2020      *
2021      * @return the actual number of bytes read in from the specified channel
2022      *
2023      * @throws IndexOutOfBoundsException
2024      *         if {@code length} is greater than {@code this.writableBytes}
2025      * @throws IOException
2026      *         if the specified channel threw an exception during I/O
2027      */
2028     public abstract int writeBytes(ScatteringByteChannel in, int length) throws IOException;
2029 
2030     /**
2031      * Transfers the content of the specified channel starting at the given file position
2032      * to this buffer starting at the current {@code writerIndex} and increases the
2033      * {@code writerIndex} by the number of the transferred bytes.
2034      * This method does not modify the channel's position.
2035      *
2036      * @param position the file position at which the transfer is to begin
2037      * @param length the maximum number of bytes to transfer
2038      *
2039      * @return the actual number of bytes read in from the specified channel
2040      *
2041      * @throws IndexOutOfBoundsException
2042      *         if {@code length} is greater than {@code this.writableBytes}
2043      * @throws IOException
2044      *         if the specified channel threw an exception during I/O
2045      */
2046     public abstract int writeBytes(FileChannel in, long position, int length) throws IOException;
2047 
2048     /**
2049      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the current
2050      * {@code writerIndex} and increases the {@code writerIndex} by the
2051      * specified {@code length}.
2052      *
2053      * @param length the number of <tt>NUL</tt>s to write to the buffer
2054      *
2055      * @throws IndexOutOfBoundsException
2056      *         if {@code length} is greater than {@code this.writableBytes}
2057      */
2058     public abstract ByteBuf writeZero(int length);
2059 
2060     /**
2061      * Writes the specified {@link CharSequence} at the current {@code writerIndex} and increases
2062      * the {@code writerIndex} by the written bytes.
2063      * in this buffer.
2064      *
2065      * @param sequence to write
2066      * @param charset that should be used
2067      * @return the written number of bytes
2068      * @throws IndexOutOfBoundsException
2069      *         if {@code this.writableBytes} is not large enough to write the whole sequence
2070      */
2071     public abstract int writeCharSequence(CharSequence sequence, Charset charset);
2072 
2073     /**
2074      * Locates the first occurrence of the specified {@code value} in this
2075      * buffer.  The search takes place from the specified {@code fromIndex}
2076      * (inclusive)  to the specified {@code toIndex} (exclusive).
2077      * <p>
2078      * If {@code fromIndex} is greater than {@code toIndex}, the search is
2079      * performed in a reversed order.
2080      * <p>
2081      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2082      * this buffer.
2083      *
2084      * @return the absolute index of the first occurrence if found.
2085      *         {@code -1} otherwise.
2086      */
2087     public abstract int indexOf(int fromIndex, int toIndex, byte value);
2088 
2089     /**
2090      * Locates the first occurrence of the specified {@code value} in this
2091      * buffer.  The search takes place from the current {@code readerIndex}
2092      * (inclusive) to the current {@code writerIndex} (exclusive).
2093      * <p>
2094      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2095      * this buffer.
2096      *
2097      * @return the number of bytes between the current {@code readerIndex}
2098      *         and the first occurrence if found. {@code -1} otherwise.
2099      */
2100     public abstract int bytesBefore(byte value);
2101 
2102     /**
2103      * Locates the first occurrence of the specified {@code value} in this
2104      * buffer.  The search starts from the current {@code readerIndex}
2105      * (inclusive) and lasts for the specified {@code length}.
2106      * <p>
2107      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2108      * this buffer.
2109      *
2110      * @return the number of bytes between the current {@code readerIndex}
2111      *         and the first occurrence if found. {@code -1} otherwise.
2112      *
2113      * @throws IndexOutOfBoundsException
2114      *         if {@code length} is greater than {@code this.readableBytes}
2115      */
2116     public abstract int bytesBefore(int length, byte value);
2117 
2118     /**
2119      * Locates the first occurrence of the specified {@code value} in this
2120      * buffer.  The search starts from the specified {@code index} (inclusive)
2121      * and lasts for the specified {@code length}.
2122      * <p>
2123      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2124      * this buffer.
2125      *
2126      * @return the number of bytes between the specified {@code index}
2127      *         and the first occurrence if found. {@code -1} otherwise.
2128      *
2129      * @throws IndexOutOfBoundsException
2130      *         if {@code index + length} is greater than {@code this.capacity}
2131      */
2132     public abstract int bytesBefore(int index, int length, byte value);
2133 
2134     /**
2135      * Iterates over the readable bytes of this buffer with the specified {@code processor} in ascending order.
2136      *
2137      * @return {@code -1} if the processor iterated to or beyond the end of the readable bytes.
2138      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2139      */
2140     public abstract int forEachByte(ByteProcessor processor);
2141 
2142     /**
2143      * Iterates over the specified area of this buffer with the specified {@code processor} in ascending order.
2144      * (i.e. {@code index}, {@code (index + 1)},  .. {@code (index + length - 1)})
2145      *
2146      * @return {@code -1} if the processor iterated to or beyond the end of the specified area.
2147      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2148      */
2149     public abstract int forEachByte(int index, int length, ByteProcessor processor);
2150 
2151     /**
2152      * Iterates over the readable bytes of this buffer with the specified {@code processor} in descending order.
2153      *
2154      * @return {@code -1} if the processor iterated to or beyond the beginning of the readable bytes.
2155      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2156      */
2157     public abstract int forEachByteDesc(ByteProcessor processor);
2158 
2159     /**
2160      * Iterates over the specified area of this buffer with the specified {@code processor} in descending order.
2161      * (i.e. {@code (index + length - 1)}, {@code (index + length - 2)}, ... {@code index})
2162      *
2163      *
2164      * @return {@code -1} if the processor iterated to or beyond the beginning of the specified area.
2165      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2166      */
2167     public abstract int forEachByteDesc(int index, int length, ByteProcessor processor);
2168 
2169     /**
2170      * Returns a copy of this buffer's readable bytes.  Modifying the content
2171      * of the returned buffer or this buffer does not affect each other at all.
2172      * This method is identical to {@code buf.copy(buf.readerIndex(), buf.readableBytes())}.
2173      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2174      * this buffer.
2175      */
2176     public abstract ByteBuf copy();
2177 
2178     /**
2179      * Returns a copy of this buffer's sub-region.  Modifying the content of
2180      * the returned buffer or this buffer does not affect each other at all.
2181      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2182      * this buffer.
2183      */
2184     public abstract ByteBuf copy(int index, int length);
2185 
2186     /**
2187      * Returns a slice of this buffer's readable bytes. Modifying the content
2188      * of the returned buffer or this buffer affects each other's content
2189      * while they maintain separate indexes and marks.  This method is
2190      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2191      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2192      * this buffer.
2193      * <p>
2194      * Also be aware that this method will NOT call {@link #retain()} and so the
2195      * reference count will NOT be increased.
2196      */
2197     public abstract ByteBuf slice();
2198 
2199     /**
2200      * Returns a retained slice of this buffer's readable bytes. Modifying the content
2201      * of the returned buffer or this buffer affects each other's content
2202      * while they maintain separate indexes and marks.  This method is
2203      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2204      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2205      * this buffer.
2206      * <p>
2207      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice()}.
2208      * This method behaves similarly to {@code slice().retain()} except that this method may return
2209      * a buffer implementation that produces less garbage.
2210      */
2211     public abstract ByteBuf retainedSlice();
2212 
2213     /**
2214      * Returns a slice of this buffer's sub-region. Modifying the content of
2215      * the returned buffer or this buffer affects each other's content while
2216      * they maintain separate indexes and marks.
2217      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2218      * this buffer.
2219      * <p>
2220      * Also be aware that this method will NOT call {@link #retain()} and so the
2221      * reference count will NOT be increased.
2222      */
2223     public abstract ByteBuf slice(int index, int length);
2224 
2225     /**
2226      * Returns a retained slice of this buffer's sub-region. Modifying the content of
2227      * the returned buffer or this buffer affects each other's content while
2228      * they maintain separate indexes and marks.
2229      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2230      * this buffer.
2231      * <p>
2232      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2233      * This method behaves similarly to {@code slice(...).retain()} except that this method may return
2234      * a buffer implementation that produces less garbage.
2235      */
2236     public abstract ByteBuf retainedSlice(int index, int length);
2237 
2238     /**
2239      * Returns a buffer which shares the whole region of this buffer.
2240      * Modifying the content of the returned buffer or this buffer affects
2241      * each other's content while they maintain separate indexes and marks.
2242      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2243      * this buffer.
2244      * <p>
2245      * The reader and writer marks will not be duplicated. Also be aware that this method will
2246      * NOT call {@link #retain()} and so the reference count will NOT be increased.
2247      * @return A buffer whose readable content is equivalent to the buffer returned by {@link #slice()}.
2248      * However this buffer will share the capacity of the underlying buffer, and therefore allows access to all of the
2249      * underlying content if necessary.
2250      */
2251     public abstract ByteBuf duplicate();
2252 
2253     /**
2254      * Returns a retained buffer which shares the whole region of this buffer.
2255      * Modifying the content of the returned buffer or this buffer affects
2256      * each other's content while they maintain separate indexes and marks.
2257      * This method is identical to {@code buf.slice(0, buf.capacity())}.
2258      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2259      * this buffer.
2260      * <p>
2261      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2262      * This method behaves similarly to {@code duplicate().retain()} except that this method may return
2263      * a buffer implementation that produces less garbage.
2264      */
2265     public abstract ByteBuf retainedDuplicate();
2266 
2267     /**
2268      * Returns the maximum number of NIO {@link ByteBuffer}s that consist this buffer.  Note that {@link #nioBuffers()}
2269      * or {@link #nioBuffers(int, int)} might return a less number of {@link ByteBuffer}s.
2270      *
2271      * @return {@code -1} if this buffer has no underlying {@link ByteBuffer}.
2272      *         the number of the underlying {@link ByteBuffer}s if this buffer has at least one underlying
2273      *         {@link ByteBuffer}.  Note that this method does not return {@code 0} to avoid confusion.
2274      *
2275      * @see #nioBuffer()
2276      * @see #nioBuffer(int, int)
2277      * @see #nioBuffers()
2278      * @see #nioBuffers(int, int)
2279      */
2280     public abstract int nioBufferCount();
2281 
2282     /**
2283      * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}.  The returned buffer
2284      * shares the content with this buffer, while changing the position and limit of the returned
2285      * NIO buffer does not affect the indexes and marks of this buffer.  This method is identical
2286      * to {@code buf.nioBuffer(buf.readerIndex(), buf.readableBytes())}.  This method does not
2287      * modify {@code readerIndex} or {@code writerIndex} of this buffer.  Please note that the
2288      * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2289      * buffer and it adjusted its capacity.
2290      *
2291      * @throws UnsupportedOperationException
2292      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2293      *
2294      * @see #nioBufferCount()
2295      * @see #nioBuffers()
2296      * @see #nioBuffers(int, int)
2297      */
2298     public abstract ByteBuffer nioBuffer();
2299 
2300     /**
2301      * Exposes this buffer's sub-region as an NIO {@link ByteBuffer}.  The returned buffer
2302      * shares the content with this buffer, while changing the position and limit of the returned
2303      * NIO buffer does not affect the indexes and marks of this buffer.  This method does not
2304      * modify {@code readerIndex} or {@code writerIndex} of this buffer.  Please note that the
2305      * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2306      * buffer and it adjusted its capacity.
2307      *
2308      * @throws UnsupportedOperationException
2309      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2310      *
2311      * @see #nioBufferCount()
2312      * @see #nioBuffers()
2313      * @see #nioBuffers(int, int)
2314      */
2315     public abstract ByteBuffer nioBuffer(int index, int length);
2316 
2317     /**
2318      * Internal use only: Exposes the internal NIO buffer.
2319      */
2320     public abstract ByteBuffer internalNioBuffer(int index, int length);
2321 
2322     /**
2323      * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}'s.  The returned buffer
2324      * shares the content with this buffer, while changing the position and limit of the returned
2325      * NIO buffer does not affect the indexes and marks of this buffer. This method does not
2326      * modify {@code readerIndex} or {@code writerIndex} of this buffer.  Please note that the
2327      * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2328      * buffer and it adjusted its capacity.
2329      *
2330      *
2331      * @throws UnsupportedOperationException
2332      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2333      *
2334      * @see #nioBufferCount()
2335      * @see #nioBuffer()
2336      * @see #nioBuffer(int, int)
2337      */
2338     public abstract ByteBuffer[] nioBuffers();
2339 
2340     /**
2341      * Exposes this buffer's bytes as an NIO {@link ByteBuffer}'s for the specified index and length
2342      * The returned buffer shares the content with this buffer, while changing the position and limit
2343      * of the returned NIO buffer does not affect the indexes and marks of this buffer. This method does
2344      * not modify {@code readerIndex} or {@code writerIndex} of this buffer.  Please note that the
2345      * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2346      * buffer and it adjusted its capacity.
2347      *
2348      * @throws UnsupportedOperationException
2349      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2350      *
2351      * @see #nioBufferCount()
2352      * @see #nioBuffer()
2353      * @see #nioBuffer(int, int)
2354      */
2355     public abstract ByteBuffer[] nioBuffers(int index, int length);
2356 
2357     /**
2358      * Returns {@code true} if and only if this buffer has a backing byte array.
2359      * If this method returns true, you can safely call {@link #array()} and
2360      * {@link #arrayOffset()}.
2361      */
2362     public abstract boolean hasArray();
2363 
2364     /**
2365      * Returns the backing byte array of this buffer.
2366      *
2367      * @throws UnsupportedOperationException
2368      *         if there no accessible backing byte array
2369      */
2370     public abstract byte[] array();
2371 
2372     /**
2373      * Returns the offset of the first byte within the backing byte array of
2374      * this buffer.
2375      *
2376      * @throws UnsupportedOperationException
2377      *         if there no accessible backing byte array
2378      */
2379     public abstract int arrayOffset();
2380 
2381     /**
2382      * Returns {@code true} if and only if this buffer has a reference to the low-level memory address that points
2383      * to the backing data.
2384      */
2385     public abstract boolean hasMemoryAddress();
2386 
2387     /**
2388      * Returns the low-level memory address that point to the first byte of ths backing data.
2389      *
2390      * @throws UnsupportedOperationException
2391      *         if this buffer does not support accessing the low-level memory address
2392      */
2393     public abstract long memoryAddress();
2394 
2395     /**
2396      * Decodes this buffer's readable bytes into a string with the specified
2397      * character set name.  This method is identical to
2398      * {@code buf.toString(buf.readerIndex(), buf.readableBytes(), charsetName)}.
2399      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2400      * this buffer.
2401      *
2402      * @throws UnsupportedCharsetException
2403      *         if the specified character set name is not supported by the
2404      *         current VM
2405      */
2406     public abstract String toString(Charset charset);
2407 
2408     /**
2409      * Decodes this buffer's sub-region into a string with the specified
2410      * character set.  This method does not modify {@code readerIndex} or
2411      * {@code writerIndex} of this buffer.
2412      */
2413     public abstract String toString(int index, int length, Charset charset);
2414 
2415     /**
2416      * Returns a hash code which was calculated from the content of this
2417      * buffer.  If there's a byte array which is
2418      * {@linkplain #equals(Object) equal to} this array, both arrays should
2419      * return the same value.
2420      */
2421     @Override
2422     public abstract int hashCode();
2423 
2424     /**
2425      * Determines if the content of the specified buffer is identical to the
2426      * content of this array.  'Identical' here means:
2427      * <ul>
2428      * <li>the size of the contents of the two buffers are same and</li>
2429      * <li>every single byte of the content of the two buffers are same.</li>
2430      * </ul>
2431      * Please note that it does not compare {@link #readerIndex()} nor
2432      * {@link #writerIndex()}.  This method also returns {@code false} for
2433      * {@code null} and an object which is not an instance of
2434      * {@link ByteBuf} type.
2435      */
2436     @Override
2437     public abstract boolean equals(Object obj);
2438 
2439     /**
2440      * Compares the content of the specified buffer to the content of this
2441      * buffer. Comparison is performed in the same manner with the string
2442      * comparison functions of various languages such as {@code strcmp},
2443      * {@code memcmp} and {@link String#compareTo(String)}.
2444      */
2445     @Override
2446     public abstract int compareTo(ByteBuf buffer);
2447 
2448     /**
2449      * Returns the string representation of this buffer.  This method does not
2450      * necessarily return the whole content of the buffer but returns
2451      * the values of the key properties such as {@link #readerIndex()},
2452      * {@link #writerIndex()} and {@link #capacity()}.
2453      */
2454     @Override
2455     public abstract String toString();
2456 
2457     @Override
2458     public abstract ByteBuf retain(int increment);
2459 
2460     @Override
2461     public abstract ByteBuf retain();
2462 
2463     @Override
2464     public abstract ByteBuf touch();
2465 
2466     @Override
2467     public abstract ByteBuf touch(Object hint);
2468 }