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      * @throws IllegalArgumentException if the {@code newCapacity} is greater than {@link #maxCapacity()}
263      */
264     public abstract ByteBuf capacity(int newCapacity);
265 
266     /**
267      * Returns the maximum allowed capacity of this buffer. This value provides an upper
268      * bound on {@link #capacity()}.
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      * Expands the buffer {@link #capacity()} to make sure the number of
517      * {@linkplain #writableBytes() writable bytes} is equal to or greater than the
518      * specified value.  If there are enough writable bytes in this buffer, this method
519      * returns with no side effect.
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      * @see #capacity(int)
526      */
527     public abstract ByteBuf ensureWritable(int minWritableBytes);
528 
529     /**
530      * Expands the buffer {@link #capacity()} to make sure the number of
531      * {@linkplain #writableBytes() writable bytes} is equal to or greater than the
532      * specified value. Unlike {@link #ensureWritable(int)}, this method returns a status code.
533      *
534      * @param minWritableBytes
535      *        the expected minimum number of writable bytes
536      * @param force
537      *        When {@link #writerIndex()} + {@code minWritableBytes} &gt; {@link #maxCapacity()}:
538      *        <ul>
539      *        <li>{@code true} - the capacity of the buffer is expanded to {@link #maxCapacity()}</li>
540      *        <li>{@code false} - the capacity of the buffer is unchanged</li>
541      *        </ul>
542      * @return {@code 0} if the buffer has enough writable bytes, and its capacity is unchanged.
543      *         {@code 1} if the buffer does not have enough bytes, and its capacity is unchanged.
544      *         {@code 2} if the buffer has enough writable bytes, and its capacity has been increased.
545      *         {@code 3} if the buffer does not have enough bytes, but its capacity has been
546      *                   increased to its maximum.
547      */
548     public abstract int ensureWritable(int minWritableBytes, boolean force);
549 
550     /**
551      * Gets a boolean at the specified absolute (@code index) in this buffer.
552      * This method does not modify the {@code readerIndex} or {@code writerIndex}
553      * of this buffer.
554      *
555      * @throws IndexOutOfBoundsException
556      *         if the specified {@code index} is less than {@code 0} or
557      *         {@code index + 1} is greater than {@code this.capacity}
558      */
559     public abstract boolean getBoolean(int index);
560 
561     /**
562      * Gets a byte at the specified absolute {@code index} in this buffer.
563      * This method does not modify {@code readerIndex} or {@code writerIndex} of
564      * this buffer.
565      *
566      * @throws IndexOutOfBoundsException
567      *         if the specified {@code index} is less than {@code 0} or
568      *         {@code index + 1} is greater than {@code this.capacity}
569      */
570     public abstract byte  getByte(int index);
571 
572     /**
573      * Gets an unsigned byte at the specified absolute {@code index} in this
574      * buffer.  This method does not modify {@code readerIndex} or
575      * {@code writerIndex} of this buffer.
576      *
577      * @throws IndexOutOfBoundsException
578      *         if the specified {@code index} is less than {@code 0} or
579      *         {@code index + 1} is greater than {@code this.capacity}
580      */
581     public abstract short getUnsignedByte(int index);
582 
583     /**
584      * Gets a 16-bit short integer at the specified absolute {@code index} in
585      * this buffer.  This method does not modify {@code readerIndex} or
586      * {@code writerIndex} of this buffer.
587      *
588      * @throws IndexOutOfBoundsException
589      *         if the specified {@code index} is less than {@code 0} or
590      *         {@code index + 2} is greater than {@code this.capacity}
591      */
592     public abstract short getShort(int index);
593 
594     /**
595      * Gets a 16-bit short integer at the specified absolute {@code index} in
596      * this buffer in Little Endian Byte Order. This method does not modify
597      * {@code readerIndex} or {@code writerIndex} of this buffer.
598      *
599      * @throws IndexOutOfBoundsException
600      *         if the specified {@code index} is less than {@code 0} or
601      *         {@code index + 2} is greater than {@code this.capacity}
602      */
603     public abstract short getShortLE(int index);
604 
605     /**
606      * Gets an unsigned 16-bit short integer at the specified absolute
607      * {@code index} in this buffer.  This method does not modify
608      * {@code readerIndex} or {@code writerIndex} of this buffer.
609      *
610      * @throws IndexOutOfBoundsException
611      *         if the specified {@code index} is less than {@code 0} or
612      *         {@code index + 2} is greater than {@code this.capacity}
613      */
614     public abstract int getUnsignedShort(int index);
615 
616     /**
617      * Gets an unsigned 16-bit short integer at the specified absolute
618      * {@code index} in this buffer in Little Endian Byte Order.
619      * This method does not modify {@code readerIndex} or
620      * {@code writerIndex} of this buffer.
621      *
622      * @throws IndexOutOfBoundsException
623      *         if the specified {@code index} is less than {@code 0} or
624      *         {@code index + 2} is greater than {@code this.capacity}
625      */
626     public abstract int getUnsignedShortLE(int index);
627 
628     /**
629      * Gets a 24-bit medium integer at the specified absolute {@code index} in
630      * this buffer.  This method does not modify {@code readerIndex} or
631      * {@code writerIndex} of this buffer.
632      *
633      * @throws IndexOutOfBoundsException
634      *         if the specified {@code index} is less than {@code 0} or
635      *         {@code index + 3} is greater than {@code this.capacity}
636      */
637     public abstract int   getMedium(int index);
638 
639     /**
640      * Gets a 24-bit medium integer at the specified absolute {@code index} in
641      * this buffer in the Little Endian Byte Order. This method does not
642      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
643      *
644      * @throws IndexOutOfBoundsException
645      *         if the specified {@code index} is less than {@code 0} or
646      *         {@code index + 3} is greater than {@code this.capacity}
647      */
648     public abstract int getMediumLE(int index);
649 
650     /**
651      * Gets an unsigned 24-bit medium integer at the specified absolute
652      * {@code index} in this buffer.  This method does not modify
653      * {@code readerIndex} or {@code writerIndex} of this buffer.
654      *
655      * @throws IndexOutOfBoundsException
656      *         if the specified {@code index} is less than {@code 0} or
657      *         {@code index + 3} is greater than {@code this.capacity}
658      */
659     public abstract int   getUnsignedMedium(int index);
660 
661     /**
662      * Gets an unsigned 24-bit medium integer at the specified absolute
663      * {@code index} in this buffer in Little Endian Byte Order.
664      * This method does not modify {@code readerIndex} or
665      * {@code writerIndex} of this buffer.
666      *
667      * @throws IndexOutOfBoundsException
668      *         if the specified {@code index} is less than {@code 0} or
669      *         {@code index + 3} is greater than {@code this.capacity}
670      */
671     public abstract int   getUnsignedMediumLE(int index);
672 
673     /**
674      * Gets a 32-bit integer at the specified absolute {@code index} in
675      * this buffer.  This method does not modify {@code readerIndex} or
676      * {@code writerIndex} of this buffer.
677      *
678      * @throws IndexOutOfBoundsException
679      *         if the specified {@code index} is less than {@code 0} or
680      *         {@code index + 4} is greater than {@code this.capacity}
681      */
682     public abstract int   getInt(int index);
683 
684     /**
685      * Gets a 32-bit integer at the specified absolute {@code index} in
686      * this buffer with Little Endian Byte Order. This method does not
687      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
688      *
689      * @throws IndexOutOfBoundsException
690      *         if the specified {@code index} is less than {@code 0} or
691      *         {@code index + 4} is greater than {@code this.capacity}
692      */
693     public abstract int   getIntLE(int index);
694 
695     /**
696      * Gets an unsigned 32-bit integer at the specified absolute {@code index}
697      * in this buffer.  This method does not modify {@code readerIndex} or
698      * {@code writerIndex} of this buffer.
699      *
700      * @throws IndexOutOfBoundsException
701      *         if the specified {@code index} is less than {@code 0} or
702      *         {@code index + 4} is greater than {@code this.capacity}
703      */
704     public abstract long  getUnsignedInt(int index);
705 
706     /**
707      * Gets an unsigned 32-bit integer at the specified absolute {@code index}
708      * in this buffer in Little Endian Byte Order. This method does not
709      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
710      *
711      * @throws IndexOutOfBoundsException
712      *         if the specified {@code index} is less than {@code 0} or
713      *         {@code index + 4} is greater than {@code this.capacity}
714      */
715     public abstract long  getUnsignedIntLE(int index);
716 
717     /**
718      * Gets a 64-bit long integer at the specified absolute {@code index} in
719      * this buffer.  This method does not modify {@code readerIndex} or
720      * {@code writerIndex} of this buffer.
721      *
722      * @throws IndexOutOfBoundsException
723      *         if the specified {@code index} is less than {@code 0} or
724      *         {@code index + 8} is greater than {@code this.capacity}
725      */
726     public abstract long  getLong(int index);
727 
728     /**
729      * Gets a 64-bit long integer at the specified absolute {@code index} in
730      * this buffer in Little Endian Byte Order. This method does not
731      * modify {@code readerIndex} or {@code writerIndex} of this buffer.
732      *
733      * @throws IndexOutOfBoundsException
734      *         if the specified {@code index} is less than {@code 0} or
735      *         {@code index + 8} is greater than {@code this.capacity}
736      */
737     public abstract long  getLongLE(int index);
738 
739     /**
740      * Gets a 2-byte UTF-16 character at the specified absolute
741      * {@code index} in this buffer.  This method does not modify
742      * {@code readerIndex} or {@code writerIndex} of this buffer.
743      *
744      * @throws IndexOutOfBoundsException
745      *         if the specified {@code index} is less than {@code 0} or
746      *         {@code index + 2} is greater than {@code this.capacity}
747      */
748     public abstract char  getChar(int index);
749 
750     /**
751      * Gets a 32-bit floating point number at the specified absolute
752      * {@code index} in this buffer.  This method does not modify
753      * {@code readerIndex} or {@code writerIndex} of this buffer.
754      *
755      * @throws IndexOutOfBoundsException
756      *         if the specified {@code index} is less than {@code 0} or
757      *         {@code index + 4} is greater than {@code this.capacity}
758      */
759     public abstract float getFloat(int index);
760 
761     /**
762      * Gets a 32-bit floating point number at the specified absolute
763      * {@code index} in this buffer in Little Endian Byte Order.
764      * This method does not modify {@code readerIndex} or
765      * {@code writerIndex} of this buffer.
766      *
767      * @throws IndexOutOfBoundsException
768      *         if the specified {@code index} is less than {@code 0} or
769      *         {@code index + 4} is greater than {@code this.capacity}
770      */
771     public float getFloatLE(int index) {
772         return Float.intBitsToFloat(getIntLE(index));
773     }
774 
775     /**
776      * Gets a 64-bit floating point number at the specified absolute
777      * {@code index} in this buffer.  This method does not modify
778      * {@code readerIndex} or {@code writerIndex} of this buffer.
779      *
780      * @throws IndexOutOfBoundsException
781      *         if the specified {@code index} is less than {@code 0} or
782      *         {@code index + 8} is greater than {@code this.capacity}
783      */
784     public abstract double getDouble(int index);
785 
786     /**
787      * Gets a 64-bit floating point number at the specified absolute
788      * {@code index} in this buffer in Little Endian Byte Order.
789      * This method does not modify {@code readerIndex} or
790      * {@code writerIndex} of this buffer.
791      *
792      * @throws IndexOutOfBoundsException
793      *         if the specified {@code index} is less than {@code 0} or
794      *         {@code index + 8} is greater than {@code this.capacity}
795      */
796     public double getDoubleLE(int index) {
797         return Double.longBitsToDouble(getLongLE(index));
798     }
799 
800     /**
801      * Transfers this buffer's data to the specified destination starting at
802      * the specified absolute {@code index} until the destination becomes
803      * non-writable.  This method is basically same with
804      * {@link #getBytes(int, ByteBuf, int, int)}, except that this
805      * method increases the {@code writerIndex} of the destination by the
806      * number of the transferred bytes while
807      * {@link #getBytes(int, ByteBuf, int, int)} does not.
808      * This method does not modify {@code readerIndex} or {@code writerIndex} of
809      * the source buffer (i.e. {@code this}).
810      *
811      * @throws IndexOutOfBoundsException
812      *         if the specified {@code index} is less than {@code 0} or
813      *         if {@code index + dst.writableBytes} is greater than
814      *            {@code this.capacity}
815      */
816     public abstract ByteBuf getBytes(int index, ByteBuf dst);
817 
818     /**
819      * Transfers this buffer's data to the specified destination starting at
820      * the specified absolute {@code index}.  This method is basically same
821      * with {@link #getBytes(int, ByteBuf, int, int)}, except that this
822      * method increases the {@code writerIndex} of the destination by the
823      * number of the transferred bytes while
824      * {@link #getBytes(int, ByteBuf, int, int)} does not.
825      * This method does not modify {@code readerIndex} or {@code writerIndex} of
826      * the source buffer (i.e. {@code this}).
827      *
828      * @param length the number of bytes to transfer
829      *
830      * @throws IndexOutOfBoundsException
831      *         if the specified {@code index} is less than {@code 0},
832      *         if {@code index + length} is greater than
833      *            {@code this.capacity}, or
834      *         if {@code length} is greater than {@code dst.writableBytes}
835      */
836     public abstract ByteBuf getBytes(int index, ByteBuf dst, int length);
837 
838     /**
839      * Transfers this buffer's data to the specified destination starting at
840      * the specified absolute {@code index}.
841      * This method does not modify {@code readerIndex} or {@code writerIndex}
842      * of both the source (i.e. {@code this}) and the destination.
843      *
844      * @param dstIndex the first index of the destination
845      * @param length   the number of bytes to transfer
846      *
847      * @throws IndexOutOfBoundsException
848      *         if the specified {@code index} is less than {@code 0},
849      *         if the specified {@code dstIndex} is less than {@code 0},
850      *         if {@code index + length} is greater than
851      *            {@code this.capacity}, or
852      *         if {@code dstIndex + length} is greater than
853      *            {@code dst.capacity}
854      */
855     public abstract ByteBuf getBytes(int index, ByteBuf dst, int dstIndex, int length);
856 
857     /**
858      * Transfers this buffer's data to the specified destination starting at
859      * the specified absolute {@code index}.
860      * This method does not modify {@code readerIndex} or {@code writerIndex} of
861      * this buffer
862      *
863      * @throws IndexOutOfBoundsException
864      *         if the specified {@code index} is less than {@code 0} or
865      *         if {@code index + dst.length} is greater than
866      *            {@code this.capacity}
867      */
868     public abstract ByteBuf getBytes(int index, byte[] dst);
869 
870     /**
871      * Transfers this buffer's data to the specified destination starting at
872      * the specified absolute {@code index}.
873      * This method does not modify {@code readerIndex} or {@code writerIndex}
874      * of this buffer.
875      *
876      * @param dstIndex the first index of the destination
877      * @param length   the number of bytes to transfer
878      *
879      * @throws IndexOutOfBoundsException
880      *         if the specified {@code index} is less than {@code 0},
881      *         if the specified {@code dstIndex} is less than {@code 0},
882      *         if {@code index + length} is greater than
883      *            {@code this.capacity}, or
884      *         if {@code dstIndex + length} is greater than
885      *            {@code dst.length}
886      */
887     public abstract ByteBuf getBytes(int index, byte[] dst, int dstIndex, int length);
888 
889     /**
890      * Transfers this buffer's data to the specified destination starting at
891      * the specified absolute {@code index} until the destination's position
892      * reaches its limit.
893      * This method does not modify {@code readerIndex} or {@code writerIndex} of
894      * this buffer while the destination's {@code position} will be increased.
895      *
896      * @throws IndexOutOfBoundsException
897      *         if the specified {@code index} is less than {@code 0} or
898      *         if {@code index + dst.remaining()} is greater than
899      *            {@code this.capacity}
900      */
901     public abstract ByteBuf getBytes(int index, ByteBuffer dst);
902 
903     /**
904      * Transfers this buffer's data to the specified stream starting at the
905      * specified absolute {@code index}.
906      * This method does not modify {@code readerIndex} or {@code writerIndex} of
907      * this buffer.
908      *
909      * @param length the number of bytes to transfer
910      *
911      * @throws IndexOutOfBoundsException
912      *         if the specified {@code index} is less than {@code 0} or
913      *         if {@code index + length} is greater than
914      *            {@code this.capacity}
915      * @throws IOException
916      *         if the specified stream threw an exception during I/O
917      */
918     public abstract ByteBuf getBytes(int index, OutputStream out, int length) throws IOException;
919 
920     /**
921      * Transfers this buffer's data to the specified channel starting at the
922      * specified absolute {@code index}.
923      * This method does not modify {@code readerIndex} or {@code writerIndex} of
924      * this buffer.
925      *
926      * @param length the maximum number of bytes to transfer
927      *
928      * @return the actual number of bytes written out to the specified channel
929      *
930      * @throws IndexOutOfBoundsException
931      *         if the specified {@code index} is less than {@code 0} or
932      *         if {@code index + length} is greater than
933      *            {@code this.capacity}
934      * @throws IOException
935      *         if the specified channel threw an exception during I/O
936      */
937     public abstract int getBytes(int index, GatheringByteChannel out, int length) throws IOException;
938 
939     /**
940      * Transfers this buffer's data starting at the specified absolute {@code index}
941      * to the specified channel starting at the given file position.
942      * This method does not modify {@code readerIndex} or {@code writerIndex} of
943      * this buffer. This method does not modify the channel's position.
944      *
945      * @param position the file position at which the transfer is to begin
946      * @param length the maximum number of bytes to transfer
947      *
948      * @return the actual number of bytes written out to the specified channel
949      *
950      * @throws IndexOutOfBoundsException
951      *         if the specified {@code index} is less than {@code 0} or
952      *         if {@code index + length} is greater than
953      *            {@code this.capacity}
954      * @throws IOException
955      *         if the specified channel threw an exception during I/O
956      */
957     public abstract int getBytes(int index, FileChannel out, long position, int length) throws IOException;
958 
959     /**
960      * Gets a {@link CharSequence} with the given length at the given index.
961      *
962      * @param length the length to read
963      * @param charset that should be used
964      * @return the sequence
965      * @throws IndexOutOfBoundsException
966      *         if {@code length} is greater than {@code this.readableBytes}
967      */
968     public abstract CharSequence getCharSequence(int index, int length, Charset charset);
969 
970     /**
971      * Sets the specified boolean at the specified absolute {@code index} in this
972      * buffer.
973      * This method does not modify {@code readerIndex} or {@code writerIndex} of
974      * this buffer.
975      *
976      * @throws IndexOutOfBoundsException
977      *         if the specified {@code index} is less than {@code 0} or
978      *         {@code index + 1} is greater than {@code this.capacity}
979      */
980     public abstract ByteBuf setBoolean(int index, boolean value);
981 
982     /**
983      * Sets the specified byte at the specified absolute {@code index} in this
984      * buffer.  The 24 high-order bits of the specified value are ignored.
985      * This method does not modify {@code readerIndex} or {@code writerIndex} of
986      * this buffer.
987      *
988      * @throws IndexOutOfBoundsException
989      *         if the specified {@code index} is less than {@code 0} or
990      *         {@code index + 1} is greater than {@code this.capacity}
991      */
992     public abstract ByteBuf setByte(int index, int value);
993 
994     /**
995      * Sets the specified 16-bit short integer at the specified absolute
996      * {@code index} in this buffer.  The 16 high-order bits of the specified
997      * value are ignored.
998      * This method does not modify {@code readerIndex} or {@code writerIndex} of
999      * this buffer.
1000      *
1001      * @throws IndexOutOfBoundsException
1002      *         if the specified {@code index} is less than {@code 0} or
1003      *         {@code index + 2} is greater than {@code this.capacity}
1004      */
1005     public abstract ByteBuf setShort(int index, int value);
1006 
1007     /**
1008      * Sets the specified 16-bit short integer at the specified absolute
1009      * {@code index} in this buffer with the Little Endian Byte Order.
1010      * The 16 high-order bits of the specified value are ignored.
1011      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1012      * this buffer.
1013      *
1014      * @throws IndexOutOfBoundsException
1015      *         if the specified {@code index} is less than {@code 0} or
1016      *         {@code index + 2} is greater than {@code this.capacity}
1017      */
1018     public abstract ByteBuf setShortLE(int index, int value);
1019 
1020     /**
1021      * Sets the specified 24-bit medium integer at the specified absolute
1022      * {@code index} in this buffer.  Please note that the most significant
1023      * byte is ignored in the specified value.
1024      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1025      * this buffer.
1026      *
1027      * @throws IndexOutOfBoundsException
1028      *         if the specified {@code index} is less than {@code 0} or
1029      *         {@code index + 3} is greater than {@code this.capacity}
1030      */
1031     public abstract ByteBuf setMedium(int index, int value);
1032 
1033     /**
1034      * Sets the specified 24-bit medium integer at the specified absolute
1035      * {@code index} in this buffer in the Little Endian Byte Order.
1036      * Please note that the most significant byte is ignored in the
1037      * specified value.
1038      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1039      * this buffer.
1040      *
1041      * @throws IndexOutOfBoundsException
1042      *         if the specified {@code index} is less than {@code 0} or
1043      *         {@code index + 3} is greater than {@code this.capacity}
1044      */
1045     public abstract ByteBuf setMediumLE(int index, int value);
1046 
1047     /**
1048      * Sets the specified 32-bit integer at the specified absolute
1049      * {@code index} in this buffer.
1050      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1051      * this buffer.
1052      *
1053      * @throws IndexOutOfBoundsException
1054      *         if the specified {@code index} is less than {@code 0} or
1055      *         {@code index + 4} is greater than {@code this.capacity}
1056      */
1057     public abstract ByteBuf setInt(int index, int value);
1058 
1059     /**
1060      * Sets the specified 32-bit integer at the specified absolute
1061      * {@code index} in this buffer with Little Endian byte order
1062      * .
1063      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1064      * this buffer.
1065      *
1066      * @throws IndexOutOfBoundsException
1067      *         if the specified {@code index} is less than {@code 0} or
1068      *         {@code index + 4} is greater than {@code this.capacity}
1069      */
1070     public abstract ByteBuf setIntLE(int index, int value);
1071 
1072     /**
1073      * Sets the specified 64-bit long integer at the specified absolute
1074      * {@code index} in this buffer.
1075      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1076      * this buffer.
1077      *
1078      * @throws IndexOutOfBoundsException
1079      *         if the specified {@code index} is less than {@code 0} or
1080      *         {@code index + 8} is greater than {@code this.capacity}
1081      */
1082     public abstract ByteBuf setLong(int index, long value);
1083 
1084     /**
1085      * Sets the specified 64-bit long integer at the specified absolute
1086      * {@code index} in this buffer in Little Endian Byte Order.
1087      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1088      * this buffer.
1089      *
1090      * @throws IndexOutOfBoundsException
1091      *         if the specified {@code index} is less than {@code 0} or
1092      *         {@code index + 8} is greater than {@code this.capacity}
1093      */
1094     public abstract ByteBuf setLongLE(int index, long value);
1095 
1096     /**
1097      * Sets the specified 2-byte UTF-16 character at the specified absolute
1098      * {@code index} in this buffer.
1099      * The 16 high-order bits of the specified value are ignored.
1100      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1101      * this buffer.
1102      *
1103      * @throws IndexOutOfBoundsException
1104      *         if the specified {@code index} is less than {@code 0} or
1105      *         {@code index + 2} is greater than {@code this.capacity}
1106      */
1107     public abstract ByteBuf setChar(int index, int value);
1108 
1109     /**
1110      * Sets the specified 32-bit floating-point number at the specified
1111      * absolute {@code index} in this buffer.
1112      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1113      * this buffer.
1114      *
1115      * @throws IndexOutOfBoundsException
1116      *         if the specified {@code index} is less than {@code 0} or
1117      *         {@code index + 4} is greater than {@code this.capacity}
1118      */
1119     public abstract ByteBuf setFloat(int index, float value);
1120 
1121     /**
1122      * Sets the specified 32-bit floating-point number at the specified
1123      * absolute {@code index} in this buffer in Little Endian Byte Order.
1124      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1125      * this buffer.
1126      *
1127      * @throws IndexOutOfBoundsException
1128      *         if the specified {@code index} is less than {@code 0} or
1129      *         {@code index + 4} is greater than {@code this.capacity}
1130      */
1131     public ByteBuf setFloatLE(int index, float value) {
1132         return setIntLE(index, Float.floatToRawIntBits(value));
1133     }
1134 
1135     /**
1136      * Sets the specified 64-bit floating-point number at the specified
1137      * absolute {@code index} in this buffer.
1138      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1139      * this buffer.
1140      *
1141      * @throws IndexOutOfBoundsException
1142      *         if the specified {@code index} is less than {@code 0} or
1143      *         {@code index + 8} is greater than {@code this.capacity}
1144      */
1145     public abstract ByteBuf setDouble(int index, double value);
1146 
1147     /**
1148      * Sets the specified 64-bit floating-point number at the specified
1149      * absolute {@code index} in this buffer in Little Endian Byte Order.
1150      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1151      * this buffer.
1152      *
1153      * @throws IndexOutOfBoundsException
1154      *         if the specified {@code index} is less than {@code 0} or
1155      *         {@code index + 8} is greater than {@code this.capacity}
1156      */
1157     public ByteBuf setDoubleLE(int index, double value) {
1158         return setLongLE(index, Double.doubleToRawLongBits(value));
1159     }
1160 
1161     /**
1162      * Transfers the specified source buffer's data to this buffer starting at
1163      * the specified absolute {@code index} until the source buffer becomes
1164      * unreadable.  This method is basically same with
1165      * {@link #setBytes(int, ByteBuf, int, int)}, except that this
1166      * method increases the {@code readerIndex} of the source buffer by
1167      * the number of the transferred bytes while
1168      * {@link #setBytes(int, ByteBuf, int, int)} does not.
1169      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1170      * the source buffer (i.e. {@code this}).
1171      *
1172      * @throws IndexOutOfBoundsException
1173      *         if the specified {@code index} is less than {@code 0} or
1174      *         if {@code index + src.readableBytes} is greater than
1175      *            {@code this.capacity}
1176      */
1177     public abstract ByteBuf setBytes(int index, ByteBuf src);
1178 
1179     /**
1180      * Transfers the specified source buffer's data to this buffer starting at
1181      * the specified absolute {@code index}.  This method is basically same
1182      * with {@link #setBytes(int, ByteBuf, int, int)}, except that this
1183      * method increases the {@code readerIndex} of the source buffer by
1184      * the number of the transferred bytes while
1185      * {@link #setBytes(int, ByteBuf, int, int)} does not.
1186      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1187      * the source buffer (i.e. {@code this}).
1188      *
1189      * @param length the number of bytes to transfer
1190      *
1191      * @throws IndexOutOfBoundsException
1192      *         if the specified {@code index} is less than {@code 0},
1193      *         if {@code index + length} is greater than
1194      *            {@code this.capacity}, or
1195      *         if {@code length} is greater than {@code src.readableBytes}
1196      */
1197     public abstract ByteBuf setBytes(int index, ByteBuf src, int length);
1198 
1199     /**
1200      * Transfers the specified source buffer's data to this buffer starting at
1201      * the specified absolute {@code index}.
1202      * This method does not modify {@code readerIndex} or {@code writerIndex}
1203      * of both the source (i.e. {@code this}) and the destination.
1204      *
1205      * @param srcIndex the first index of the source
1206      * @param length   the number of bytes to transfer
1207      *
1208      * @throws IndexOutOfBoundsException
1209      *         if the specified {@code index} is less than {@code 0},
1210      *         if the specified {@code srcIndex} is less than {@code 0},
1211      *         if {@code index + length} is greater than
1212      *            {@code this.capacity}, or
1213      *         if {@code srcIndex + length} is greater than
1214      *            {@code src.capacity}
1215      */
1216     public abstract ByteBuf setBytes(int index, ByteBuf src, int srcIndex, int length);
1217 
1218     /**
1219      * Transfers the specified source array's data to this buffer starting at
1220      * the specified absolute {@code index}.
1221      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1222      * this buffer.
1223      *
1224      * @throws IndexOutOfBoundsException
1225      *         if the specified {@code index} is less than {@code 0} or
1226      *         if {@code index + src.length} is greater than
1227      *            {@code this.capacity}
1228      */
1229     public abstract ByteBuf setBytes(int index, byte[] src);
1230 
1231     /**
1232      * Transfers the specified source array's data to this buffer starting at
1233      * the specified absolute {@code index}.
1234      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1235      * this buffer.
1236      *
1237      * @throws IndexOutOfBoundsException
1238      *         if the specified {@code index} is less than {@code 0},
1239      *         if the specified {@code srcIndex} is less than {@code 0},
1240      *         if {@code index + length} is greater than
1241      *            {@code this.capacity}, or
1242      *         if {@code srcIndex + length} is greater than {@code src.length}
1243      */
1244     public abstract ByteBuf setBytes(int index, byte[] src, int srcIndex, int length);
1245 
1246     /**
1247      * Transfers the specified source buffer's data to this buffer starting at
1248      * the specified absolute {@code index} until the source buffer's position
1249      * reaches its limit.
1250      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1251      * this buffer.
1252      *
1253      * @throws IndexOutOfBoundsException
1254      *         if the specified {@code index} is less than {@code 0} or
1255      *         if {@code index + src.remaining()} is greater than
1256      *            {@code this.capacity}
1257      */
1258     public abstract ByteBuf setBytes(int index, ByteBuffer src);
1259 
1260     /**
1261      * Transfers the content of the specified source stream to this buffer
1262      * starting at the specified absolute {@code index}.
1263      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1264      * this buffer.
1265      *
1266      * @param length the number of bytes to transfer
1267      *
1268      * @return the actual number of bytes read in from the specified channel.
1269      *         {@code -1} if the specified channel is closed.
1270      *
1271      * @throws IndexOutOfBoundsException
1272      *         if the specified {@code index} is less than {@code 0} or
1273      *         if {@code index + length} is greater than {@code this.capacity}
1274      * @throws IOException
1275      *         if the specified stream threw an exception during I/O
1276      */
1277     public abstract int setBytes(int index, InputStream in, int length) throws IOException;
1278 
1279     /**
1280      * Transfers the content of the specified source channel to this buffer
1281      * starting at the specified absolute {@code index}.
1282      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1283      * this buffer.
1284      *
1285      * @param length the maximum number of bytes to transfer
1286      *
1287      * @return the actual number of bytes read in from the specified channel.
1288      *         {@code -1} if the specified channel is closed.
1289      *
1290      * @throws IndexOutOfBoundsException
1291      *         if the specified {@code index} is less than {@code 0} or
1292      *         if {@code index + length} is greater than {@code this.capacity}
1293      * @throws IOException
1294      *         if the specified channel threw an exception during I/O
1295      */
1296     public abstract int setBytes(int index, ScatteringByteChannel in, int length) throws IOException;
1297 
1298     /**
1299      * Transfers the content of the specified source channel starting at the given file position
1300      * to this buffer starting at the specified absolute {@code index}.
1301      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1302      * this buffer. This method does not modify the channel's position.
1303      *
1304      * @param position the file position at which the transfer is to begin
1305      * @param length the maximum number of bytes to transfer
1306      *
1307      * @return the actual number of bytes read in from the specified channel.
1308      *         {@code -1} if the specified channel is closed.
1309      *
1310      * @throws IndexOutOfBoundsException
1311      *         if the specified {@code index} is less than {@code 0} or
1312      *         if {@code index + length} is greater than {@code this.capacity}
1313      * @throws IOException
1314      *         if the specified channel threw an exception during I/O
1315      */
1316     public abstract int setBytes(int index, FileChannel in, long position, int length) throws IOException;
1317 
1318     /**
1319      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the specified
1320      * absolute {@code index}.
1321      * This method does not modify {@code readerIndex} or {@code writerIndex} of
1322      * this buffer.
1323      *
1324      * @param length the number of <tt>NUL</tt>s to write to the buffer
1325      *
1326      * @throws IndexOutOfBoundsException
1327      *         if the specified {@code index} is less than {@code 0} or
1328      *         if {@code index + length} is greater than {@code this.capacity}
1329      */
1330     public abstract ByteBuf setZero(int index, int length);
1331 
1332     /**
1333      * Writes the specified {@link CharSequence} at the current {@code writerIndex} and increases
1334      * the {@code writerIndex} by the written bytes.
1335      *
1336      * @param index on which the sequence should be written
1337      * @param sequence to write
1338      * @param charset that should be used.
1339      * @return the written number of bytes.
1340      * @throws IndexOutOfBoundsException
1341      *         if {@code this.writableBytes} is not large enough to write the whole sequence
1342      */
1343     public abstract int setCharSequence(int index, CharSequence sequence, Charset charset);
1344 
1345     /**
1346      * Gets a boolean at the current {@code readerIndex} and increases
1347      * the {@code readerIndex} by {@code 1} in this buffer.
1348      *
1349      * @throws IndexOutOfBoundsException
1350      *         if {@code this.readableBytes} is less than {@code 1}
1351      */
1352     public abstract boolean readBoolean();
1353 
1354     /**
1355      * Gets a byte at the current {@code readerIndex} and increases
1356      * the {@code readerIndex} by {@code 1} in this buffer.
1357      *
1358      * @throws IndexOutOfBoundsException
1359      *         if {@code this.readableBytes} is less than {@code 1}
1360      */
1361     public abstract byte  readByte();
1362 
1363     /**
1364      * Gets an unsigned byte at the current {@code readerIndex} and increases
1365      * the {@code readerIndex} by {@code 1} in this buffer.
1366      *
1367      * @throws IndexOutOfBoundsException
1368      *         if {@code this.readableBytes} is less than {@code 1}
1369      */
1370     public abstract short readUnsignedByte();
1371 
1372     /**
1373      * Gets a 16-bit short integer at the current {@code readerIndex}
1374      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1375      *
1376      * @throws IndexOutOfBoundsException
1377      *         if {@code this.readableBytes} is less than {@code 2}
1378      */
1379     public abstract short readShort();
1380 
1381     /**
1382      * Gets a 16-bit short integer at the current {@code readerIndex}
1383      * in the Little Endian Byte Order and increases the {@code readerIndex}
1384      * by {@code 2} in this buffer.
1385      *
1386      * @throws IndexOutOfBoundsException
1387      *         if {@code this.readableBytes} is less than {@code 2}
1388      */
1389     public abstract short readShortLE();
1390 
1391     /**
1392      * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1393      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1394      *
1395      * @throws IndexOutOfBoundsException
1396      *         if {@code this.readableBytes} is less than {@code 2}
1397      */
1398     public abstract int   readUnsignedShort();
1399 
1400     /**
1401      * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1402      * in the Little Endian Byte Order and increases the {@code readerIndex}
1403      * by {@code 2} in this buffer.
1404      *
1405      * @throws IndexOutOfBoundsException
1406      *         if {@code this.readableBytes} is less than {@code 2}
1407      */
1408     public abstract int   readUnsignedShortLE();
1409 
1410     /**
1411      * Gets a 24-bit medium integer at the current {@code readerIndex}
1412      * and increases the {@code readerIndex} by {@code 3} in this buffer.
1413      *
1414      * @throws IndexOutOfBoundsException
1415      *         if {@code this.readableBytes} is less than {@code 3}
1416      */
1417     public abstract int   readMedium();
1418 
1419     /**
1420      * Gets a 24-bit medium integer at the current {@code readerIndex}
1421      * in the Little Endian Byte Order and increases the
1422      * {@code readerIndex} by {@code 3} in this buffer.
1423      *
1424      * @throws IndexOutOfBoundsException
1425      *         if {@code this.readableBytes} is less than {@code 3}
1426      */
1427     public abstract int   readMediumLE();
1428 
1429     /**
1430      * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1431      * and increases the {@code readerIndex} by {@code 3} in this buffer.
1432      *
1433      * @throws IndexOutOfBoundsException
1434      *         if {@code this.readableBytes} is less than {@code 3}
1435      */
1436     public abstract int   readUnsignedMedium();
1437 
1438     /**
1439      * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1440      * in the Little Endian Byte Order and increases the {@code readerIndex}
1441      * by {@code 3} in this buffer.
1442      *
1443      * @throws IndexOutOfBoundsException
1444      *         if {@code this.readableBytes} is less than {@code 3}
1445      */
1446     public abstract int   readUnsignedMediumLE();
1447 
1448     /**
1449      * Gets a 32-bit integer at the current {@code readerIndex}
1450      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1451      *
1452      * @throws IndexOutOfBoundsException
1453      *         if {@code this.readableBytes} is less than {@code 4}
1454      */
1455     public abstract int   readInt();
1456 
1457     /**
1458      * Gets a 32-bit integer at the current {@code readerIndex}
1459      * in the Little Endian Byte Order and increases the {@code readerIndex}
1460      * by {@code 4} in this buffer.
1461      *
1462      * @throws IndexOutOfBoundsException
1463      *         if {@code this.readableBytes} is less than {@code 4}
1464      */
1465     public abstract int   readIntLE();
1466 
1467     /**
1468      * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1469      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1470      *
1471      * @throws IndexOutOfBoundsException
1472      *         if {@code this.readableBytes} is less than {@code 4}
1473      */
1474     public abstract long  readUnsignedInt();
1475 
1476     /**
1477      * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1478      * in the Little Endian Byte Order and increases the {@code readerIndex}
1479      * by {@code 4} in this buffer.
1480      *
1481      * @throws IndexOutOfBoundsException
1482      *         if {@code this.readableBytes} is less than {@code 4}
1483      */
1484     public abstract long  readUnsignedIntLE();
1485 
1486     /**
1487      * Gets a 64-bit integer at the current {@code readerIndex}
1488      * and increases the {@code readerIndex} by {@code 8} in this buffer.
1489      *
1490      * @throws IndexOutOfBoundsException
1491      *         if {@code this.readableBytes} is less than {@code 8}
1492      */
1493     public abstract long  readLong();
1494 
1495     /**
1496      * Gets a 64-bit integer at the current {@code readerIndex}
1497      * in the Little Endian Byte Order and increases the {@code readerIndex}
1498      * by {@code 8} in this buffer.
1499      *
1500      * @throws IndexOutOfBoundsException
1501      *         if {@code this.readableBytes} is less than {@code 8}
1502      */
1503     public abstract long  readLongLE();
1504 
1505     /**
1506      * Gets a 2-byte UTF-16 character at the current {@code readerIndex}
1507      * and increases the {@code readerIndex} by {@code 2} in this buffer.
1508      *
1509      * @throws IndexOutOfBoundsException
1510      *         if {@code this.readableBytes} is less than {@code 2}
1511      */
1512     public abstract char  readChar();
1513 
1514     /**
1515      * Gets a 32-bit floating point number at the current {@code readerIndex}
1516      * and increases the {@code readerIndex} by {@code 4} in this buffer.
1517      *
1518      * @throws IndexOutOfBoundsException
1519      *         if {@code this.readableBytes} is less than {@code 4}
1520      */
1521     public abstract float readFloat();
1522 
1523     /**
1524      * Gets a 32-bit floating point number at the current {@code readerIndex}
1525      * in Little Endian Byte Order and increases the {@code readerIndex}
1526      * by {@code 4} in this buffer.
1527      *
1528      * @throws IndexOutOfBoundsException
1529      *         if {@code this.readableBytes} is less than {@code 4}
1530      */
1531     public float readFloatLE() {
1532         return Float.intBitsToFloat(readIntLE());
1533     }
1534 
1535     /**
1536      * Gets a 64-bit floating point number at the current {@code readerIndex}
1537      * and increases the {@code readerIndex} by {@code 8} in this buffer.
1538      *
1539      * @throws IndexOutOfBoundsException
1540      *         if {@code this.readableBytes} is less than {@code 8}
1541      */
1542     public abstract double readDouble();
1543 
1544     /**
1545      * Gets a 64-bit floating point number at the current {@code readerIndex}
1546      * in Little Endian Byte Order and increases the {@code readerIndex}
1547      * by {@code 8} in this buffer.
1548      *
1549      * @throws IndexOutOfBoundsException
1550      *         if {@code this.readableBytes} is less than {@code 8}
1551      */
1552     public double readDoubleLE() {
1553         return Double.longBitsToDouble(readLongLE());
1554     }
1555 
1556     /**
1557      * Transfers this buffer's data to a newly created buffer starting at
1558      * the current {@code readerIndex} and increases the {@code readerIndex}
1559      * by the number of the transferred bytes (= {@code length}).
1560      * The returned buffer's {@code readerIndex} and {@code writerIndex} are
1561      * {@code 0} and {@code length} respectively.
1562      *
1563      * @param length the number of bytes to transfer
1564      *
1565      * @return the newly created buffer which contains the transferred bytes
1566      *
1567      * @throws IndexOutOfBoundsException
1568      *         if {@code length} is greater than {@code this.readableBytes}
1569      */
1570     public abstract ByteBuf readBytes(int length);
1571 
1572     /**
1573      * Returns a new slice of this buffer's sub-region starting at the current
1574      * {@code readerIndex} and increases the {@code readerIndex} by the size
1575      * of the new slice (= {@code length}).
1576      * <p>
1577      * Also be aware that this method will NOT call {@link #retain()} and so the
1578      * reference count will NOT be increased.
1579      *
1580      * @param length the size of the new slice
1581      *
1582      * @return the newly created slice
1583      *
1584      * @throws IndexOutOfBoundsException
1585      *         if {@code length} is greater than {@code this.readableBytes}
1586      */
1587     public abstract ByteBuf readSlice(int length);
1588 
1589     /**
1590      * Returns a new retained slice of this buffer's sub-region starting at the current
1591      * {@code readerIndex} and increases the {@code readerIndex} by the size
1592      * of the new slice (= {@code length}).
1593      * <p>
1594      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #readSlice(int)}.
1595      * This method behaves similarly to {@code readSlice(...).retain()} except that this method may return
1596      * a buffer implementation that produces less garbage.
1597      *
1598      * @param length the size of the new slice
1599      *
1600      * @return the newly created slice
1601      *
1602      * @throws IndexOutOfBoundsException
1603      *         if {@code length} is greater than {@code this.readableBytes}
1604      */
1605     public abstract ByteBuf readRetainedSlice(int length);
1606 
1607     /**
1608      * Transfers this buffer's data to the specified destination starting at
1609      * the current {@code readerIndex} until the destination becomes
1610      * non-writable, and increases the {@code readerIndex} by the number of the
1611      * transferred bytes.  This method is basically same with
1612      * {@link #readBytes(ByteBuf, int, int)}, except that this method
1613      * increases the {@code writerIndex} of the destination by the number of
1614      * the transferred bytes while {@link #readBytes(ByteBuf, int, int)}
1615      * does not.
1616      *
1617      * @throws IndexOutOfBoundsException
1618      *         if {@code dst.writableBytes} is greater than
1619      *            {@code this.readableBytes}
1620      */
1621     public abstract ByteBuf readBytes(ByteBuf dst);
1622 
1623     /**
1624      * Transfers this buffer's data to the specified destination starting at
1625      * the current {@code readerIndex} and increases the {@code readerIndex}
1626      * by the number of the transferred bytes (= {@code length}).  This method
1627      * is basically same with {@link #readBytes(ByteBuf, int, int)},
1628      * except that this method increases the {@code writerIndex} of the
1629      * destination by the number of the transferred bytes (= {@code length})
1630      * while {@link #readBytes(ByteBuf, int, int)} does not.
1631      *
1632      * @throws IndexOutOfBoundsException
1633      *         if {@code length} is greater than {@code this.readableBytes} or
1634      *         if {@code length} is greater than {@code dst.writableBytes}
1635      */
1636     public abstract ByteBuf readBytes(ByteBuf dst, int length);
1637 
1638     /**
1639      * Transfers this buffer's data to the specified destination starting at
1640      * the current {@code readerIndex} and increases the {@code readerIndex}
1641      * by the number of the transferred bytes (= {@code length}).
1642      *
1643      * @param dstIndex the first index of the destination
1644      * @param length   the number of bytes to transfer
1645      *
1646      * @throws IndexOutOfBoundsException
1647      *         if the specified {@code dstIndex} is less than {@code 0},
1648      *         if {@code length} is greater than {@code this.readableBytes}, or
1649      *         if {@code dstIndex + length} is greater than
1650      *            {@code dst.capacity}
1651      */
1652     public abstract ByteBuf readBytes(ByteBuf dst, int dstIndex, int length);
1653 
1654     /**
1655      * Transfers this buffer's data to the specified destination starting at
1656      * the current {@code readerIndex} and increases the {@code readerIndex}
1657      * by the number of the transferred bytes (= {@code dst.length}).
1658      *
1659      * @throws IndexOutOfBoundsException
1660      *         if {@code dst.length} is greater than {@code this.readableBytes}
1661      */
1662     public abstract ByteBuf readBytes(byte[] dst);
1663 
1664     /**
1665      * Transfers this buffer's data to the specified destination starting at
1666      * the current {@code readerIndex} and increases the {@code readerIndex}
1667      * by the number of the transferred bytes (= {@code length}).
1668      *
1669      * @param dstIndex the first index of the destination
1670      * @param length   the number of bytes to transfer
1671      *
1672      * @throws IndexOutOfBoundsException
1673      *         if the specified {@code dstIndex} is less than {@code 0},
1674      *         if {@code length} is greater than {@code this.readableBytes}, or
1675      *         if {@code dstIndex + length} is greater than {@code dst.length}
1676      */
1677     public abstract ByteBuf readBytes(byte[] dst, int dstIndex, int length);
1678 
1679     /**
1680      * Transfers this buffer's data to the specified destination starting at
1681      * the current {@code readerIndex} until the destination's position
1682      * reaches its limit, and increases the {@code readerIndex} by the
1683      * number of the transferred bytes.
1684      *
1685      * @throws IndexOutOfBoundsException
1686      *         if {@code dst.remaining()} is greater than
1687      *            {@code this.readableBytes}
1688      */
1689     public abstract ByteBuf readBytes(ByteBuffer dst);
1690 
1691     /**
1692      * Transfers this buffer's data to the specified stream starting at the
1693      * current {@code readerIndex}.
1694      *
1695      * @param length the number of bytes to transfer
1696      *
1697      * @throws IndexOutOfBoundsException
1698      *         if {@code length} is greater than {@code this.readableBytes}
1699      * @throws IOException
1700      *         if the specified stream threw an exception during I/O
1701      */
1702     public abstract ByteBuf readBytes(OutputStream out, int length) throws IOException;
1703 
1704     /**
1705      * Transfers this buffer's data to the specified stream starting at the
1706      * current {@code readerIndex}.
1707      *
1708      * @param length the maximum number of bytes to transfer
1709      *
1710      * @return the actual number of bytes written out to the specified channel
1711      *
1712      * @throws IndexOutOfBoundsException
1713      *         if {@code length} is greater than {@code this.readableBytes}
1714      * @throws IOException
1715      *         if the specified channel threw an exception during I/O
1716      */
1717     public abstract int readBytes(GatheringByteChannel out, int length) throws IOException;
1718 
1719     /**
1720      * Gets a {@link CharSequence} with the given length at the current {@code readerIndex}
1721      * and increases the {@code readerIndex} by the given length.
1722      *
1723      * @param length the length to read
1724      * @param charset that should be used
1725      * @return the sequence
1726      * @throws IndexOutOfBoundsException
1727      *         if {@code length} is greater than {@code this.readableBytes}
1728      */
1729     public abstract CharSequence readCharSequence(int length, Charset charset);
1730 
1731     /**
1732      * Transfers this buffer's data starting at the current {@code readerIndex}
1733      * to the specified channel starting at the given file position.
1734      * This method does not modify the channel's position.
1735      *
1736      * @param position the file position at which the transfer is to begin
1737      * @param length the maximum number of bytes to transfer
1738      *
1739      * @return the actual number of bytes written out to the specified channel
1740      *
1741      * @throws IndexOutOfBoundsException
1742      *         if {@code length} is greater than {@code this.readableBytes}
1743      * @throws IOException
1744      *         if the specified channel threw an exception during I/O
1745      */
1746     public abstract int readBytes(FileChannel out, long position, int length) throws IOException;
1747 
1748     /**
1749      * Increases the current {@code readerIndex} by the specified
1750      * {@code length} in this buffer.
1751      *
1752      * @throws IndexOutOfBoundsException
1753      *         if {@code length} is greater than {@code this.readableBytes}
1754      */
1755     public abstract ByteBuf skipBytes(int length);
1756 
1757     /**
1758      * Sets the specified boolean at the current {@code writerIndex}
1759      * and increases the {@code writerIndex} by {@code 1} in this buffer.
1760      * If {@code this.writableBytes} is less than {@code 1}, {@link #ensureWritable(int)}
1761      * will be called in an attempt to expand capacity to accommodate.
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      * If {@code this.writableBytes} is less than {@code 1}, {@link #ensureWritable(int)}
1770      * will be called in an attempt to expand capacity to accommodate.
1771      */
1772     public abstract ByteBuf writeByte(int value);
1773 
1774     /**
1775      * Sets the specified 16-bit short integer at the current
1776      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1777      * in this buffer.  The 16 high-order bits of the specified value are ignored.
1778      * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1779      * will be called in an attempt to expand capacity to accommodate.
1780      */
1781     public abstract ByteBuf writeShort(int value);
1782 
1783     /**
1784      * Sets the specified 16-bit short integer in the Little Endian Byte
1785      * Order at the current {@code writerIndex} and increases the
1786      * {@code writerIndex} by {@code 2} in this buffer.
1787      * The 16 high-order bits of the specified value are ignored.
1788      * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1789      * will be called in an attempt to expand capacity to accommodate.
1790      */
1791     public abstract ByteBuf writeShortLE(int value);
1792 
1793     /**
1794      * Sets the specified 24-bit medium integer at the current
1795      * {@code writerIndex} and increases the {@code writerIndex} by {@code 3}
1796      * in this buffer.
1797      * If {@code this.writableBytes} is less than {@code 3}, {@link #ensureWritable(int)}
1798      * will be called in an attempt to expand capacity to accommodate.
1799      */
1800     public abstract ByteBuf writeMedium(int value);
1801 
1802     /**
1803      * Sets the specified 24-bit medium integer at the current
1804      * {@code writerIndex} in the Little Endian Byte Order and
1805      * increases the {@code writerIndex} by {@code 3} in this
1806      * buffer.
1807      * If {@code this.writableBytes} is less than {@code 3}, {@link #ensureWritable(int)}
1808      * will be called in an attempt to expand capacity to accommodate.
1809      */
1810     public abstract ByteBuf writeMediumLE(int value);
1811 
1812     /**
1813      * Sets the specified 32-bit integer at the current {@code writerIndex}
1814      * and increases the {@code writerIndex} by {@code 4} in this buffer.
1815      * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1816      * will be called in an attempt to expand capacity to accommodate.
1817      */
1818     public abstract ByteBuf writeInt(int value);
1819 
1820     /**
1821      * Sets the specified 32-bit integer at the current {@code writerIndex}
1822      * in the Little Endian Byte Order and increases the {@code writerIndex}
1823      * by {@code 4} in this buffer.
1824      * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1825      * will be called in an attempt to expand capacity to accommodate.
1826      */
1827     public abstract ByteBuf writeIntLE(int value);
1828 
1829     /**
1830      * Sets the specified 64-bit long integer at the current
1831      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1832      * in this buffer.
1833      * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1834      * will be called in an attempt to expand capacity to accommodate.
1835      */
1836     public abstract ByteBuf writeLong(long value);
1837 
1838     /**
1839      * Sets the specified 64-bit long integer at the current
1840      * {@code writerIndex} in the Little Endian Byte Order and
1841      * increases the {@code writerIndex} by {@code 8}
1842      * in this buffer.
1843      * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1844      * will be called in an attempt to expand capacity to accommodate.
1845      */
1846     public abstract ByteBuf writeLongLE(long value);
1847 
1848     /**
1849      * Sets the specified 2-byte UTF-16 character at the current
1850      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1851      * in this buffer.  The 16 high-order bits of the specified value are ignored.
1852      * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1853      * will be called in an attempt to expand capacity to accommodate.
1854      */
1855     public abstract ByteBuf writeChar(int value);
1856 
1857     /**
1858      * Sets the specified 32-bit floating point number at the current
1859      * {@code writerIndex} and increases the {@code writerIndex} by {@code 4}
1860      * in this buffer.
1861      * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1862      * will be called in an attempt to expand capacity to accommodate.
1863      */
1864     public abstract ByteBuf writeFloat(float value);
1865 
1866     /**
1867      * Sets the specified 32-bit floating point number at the current
1868      * {@code writerIndex} in Little Endian Byte Order and increases
1869      * the {@code writerIndex} by {@code 4} in this buffer.
1870      * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1871      * will be called in an attempt to expand capacity to accommodate.
1872      */
1873     public ByteBuf writeFloatLE(float value) {
1874         return writeIntLE(Float.floatToRawIntBits(value));
1875     }
1876 
1877     /**
1878      * Sets the specified 64-bit floating point number at the current
1879      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1880      * in this buffer.
1881      * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1882      * will be called in an attempt to expand capacity to accommodate.
1883      */
1884     public abstract ByteBuf writeDouble(double value);
1885 
1886     /**
1887      * Sets the specified 64-bit floating point number at the current
1888      * {@code writerIndex} in Little Endian Byte Order and increases
1889      * the {@code writerIndex} by {@code 8} in this buffer.
1890      * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1891      * will be called in an attempt to expand capacity to accommodate.
1892      */
1893     public ByteBuf writeDoubleLE(double value) {
1894         return writeLongLE(Double.doubleToRawLongBits(value));
1895     }
1896 
1897     /**
1898      * Transfers the specified source buffer's data to this buffer starting at
1899      * the current {@code writerIndex} until the source buffer becomes
1900      * unreadable, and increases the {@code writerIndex} by the number of
1901      * the transferred bytes.  This method is basically same with
1902      * {@link #writeBytes(ByteBuf, int, int)}, except that this method
1903      * increases the {@code readerIndex} of the source buffer by the number of
1904      * the transferred bytes while {@link #writeBytes(ByteBuf, int, int)}
1905      * does not.
1906      * If {@code this.writableBytes} is less than {@code src.readableBytes},
1907      * {@link #ensureWritable(int)} will be called in an attempt to expand
1908      * capacity to accommodate.
1909      */
1910     public abstract ByteBuf writeBytes(ByteBuf src);
1911 
1912     /**
1913      * Transfers the specified source buffer's data to this buffer starting at
1914      * the current {@code writerIndex} and increases the {@code writerIndex}
1915      * by the number of the transferred bytes (= {@code length}).  This method
1916      * is basically same with {@link #writeBytes(ByteBuf, int, int)},
1917      * except that this method increases the {@code readerIndex} of the source
1918      * buffer by the number of the transferred bytes (= {@code length}) while
1919      * {@link #writeBytes(ByteBuf, int, int)} does not.
1920      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1921      * will be called in an attempt to expand capacity to accommodate.
1922      *
1923      * @param length the number of bytes to transfer
1924      * @throws IndexOutOfBoundsException if {@code length} is greater then {@code src.readableBytes}
1925      */
1926     public abstract ByteBuf writeBytes(ByteBuf src, int length);
1927 
1928     /**
1929      * Transfers the specified source buffer's data to this buffer starting at
1930      * the current {@code writerIndex} and increases the {@code writerIndex}
1931      * by the number of the transferred bytes (= {@code length}).
1932      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1933      * will be called in an attempt to expand capacity to accommodate.
1934      *
1935      * @param srcIndex the first index of the source
1936      * @param length   the number of bytes to transfer
1937      *
1938      * @throws IndexOutOfBoundsException
1939      *         if the specified {@code srcIndex} is less than {@code 0}, or
1940      *         if {@code srcIndex + length} is greater than {@code src.capacity}
1941      */
1942     public abstract ByteBuf writeBytes(ByteBuf src, int srcIndex, int length);
1943 
1944     /**
1945      * Transfers the specified source array'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 src.length}).
1948      * If {@code this.writableBytes} is less than {@code src.length}, {@link #ensureWritable(int)}
1949      * will be called in an attempt to expand capacity to accommodate.
1950      */
1951     public abstract ByteBuf writeBytes(byte[] src);
1952 
1953     /**
1954      * Transfers the specified source array's data to this buffer starting at
1955      * the current {@code writerIndex} and increases the {@code writerIndex}
1956      * by the number of the transferred bytes (= {@code length}).
1957      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1958      * will be called in an attempt to expand capacity to accommodate.
1959      *
1960      * @param srcIndex the first index of the source
1961      * @param length   the number of bytes to transfer
1962      *
1963      * @throws IndexOutOfBoundsException
1964      *         if the specified {@code srcIndex} is less than {@code 0}, or
1965      *         if {@code srcIndex + length} is greater than {@code src.length}
1966      */
1967     public abstract ByteBuf writeBytes(byte[] src, int srcIndex, int length);
1968 
1969     /**
1970      * Transfers the specified source buffer's data to this buffer starting at
1971      * the current {@code writerIndex} until the source buffer's position
1972      * reaches its limit, and increases the {@code writerIndex} by the
1973      * number of the transferred bytes.
1974      * If {@code this.writableBytes} is less than {@code src.remaining()},
1975      * {@link #ensureWritable(int)} will be called in an attempt to expand
1976      * capacity to accommodate.
1977      */
1978     public abstract ByteBuf writeBytes(ByteBuffer src);
1979 
1980     /**
1981      * Transfers the content of the specified stream to this buffer
1982      * starting at the current {@code writerIndex} and increases the
1983      * {@code writerIndex} by the number of the transferred bytes.
1984      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1985      * will be called in an attempt to expand capacity to accommodate.
1986      *
1987      * @param length the number of bytes to transfer
1988      *
1989      * @return the actual number of bytes read in from the specified stream
1990      *
1991      * @throws IOException if the specified stream threw an exception during I/O
1992      */
1993     public abstract int writeBytes(InputStream in, int length) throws IOException;
1994 
1995     /**
1996      * Transfers the content of the specified channel to this buffer
1997      * starting at the current {@code writerIndex} and increases the
1998      * {@code writerIndex} by the number of the transferred bytes.
1999      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2000      * will be called in an attempt to expand capacity to accommodate.
2001      *
2002      * @param length the maximum number of bytes to transfer
2003      *
2004      * @return the actual number of bytes read in from the specified channel
2005      *
2006      * @throws IOException
2007      *         if the specified channel threw an exception during I/O
2008      */
2009     public abstract int writeBytes(ScatteringByteChannel in, int length) throws IOException;
2010 
2011     /**
2012      * Transfers the content of the specified channel starting at the given file position
2013      * to this buffer starting at the current {@code writerIndex} and increases the
2014      * {@code writerIndex} by the number of the transferred bytes.
2015      * This method does not modify the channel's position.
2016      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2017      * will be called in an attempt to expand capacity to accommodate.
2018      *
2019      * @param position the file position at which the transfer is to begin
2020      * @param length the maximum number of bytes to transfer
2021      *
2022      * @return the actual number of bytes read in from the specified channel
2023      *
2024      * @throws IOException
2025      *         if the specified channel threw an exception during I/O
2026      */
2027     public abstract int writeBytes(FileChannel in, long position, int length) throws IOException;
2028 
2029     /**
2030      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the current
2031      * {@code writerIndex} and increases the {@code writerIndex} by the
2032      * specified {@code length}.
2033      * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2034      * will be called in an attempt to expand capacity to accommodate.
2035      *
2036      * @param length the number of <tt>NUL</tt>s to write to the buffer
2037      */
2038     public abstract ByteBuf writeZero(int length);
2039 
2040     /**
2041      * Writes the specified {@link CharSequence} at the current {@code writerIndex} and increases
2042      * the {@code writerIndex} by the written bytes.
2043      * in this buffer.
2044      * If {@code this.writableBytes} is not large enough to write the whole sequence,
2045      * {@link #ensureWritable(int)} will be called in an attempt to expand capacity to accommodate.
2046      *
2047      * @param sequence to write
2048      * @param charset that should be used
2049      * @return the written number of bytes
2050      */
2051     public abstract int writeCharSequence(CharSequence sequence, Charset charset);
2052 
2053     /**
2054      * Locates the first occurrence of the specified {@code value} in this
2055      * buffer.  The search takes place from the specified {@code fromIndex}
2056      * (inclusive)  to the specified {@code toIndex} (exclusive).
2057      * <p>
2058      * If {@code fromIndex} is greater than {@code toIndex}, the search is
2059      * performed in a reversed order.
2060      * <p>
2061      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2062      * this buffer.
2063      *
2064      * @return the absolute index of the first occurrence if found.
2065      *         {@code -1} otherwise.
2066      */
2067     public abstract int indexOf(int fromIndex, int toIndex, byte value);
2068 
2069     /**
2070      * Locates the first occurrence of the specified {@code value} in this
2071      * buffer.  The search takes place from the current {@code readerIndex}
2072      * (inclusive) to the current {@code writerIndex} (exclusive).
2073      * <p>
2074      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2075      * this buffer.
2076      *
2077      * @return the number of bytes between the current {@code readerIndex}
2078      *         and the first occurrence if found. {@code -1} otherwise.
2079      */
2080     public abstract int bytesBefore(byte value);
2081 
2082     /**
2083      * Locates the first occurrence of the specified {@code value} in this
2084      * buffer.  The search starts from the current {@code readerIndex}
2085      * (inclusive) and lasts for the specified {@code length}.
2086      * <p>
2087      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2088      * this buffer.
2089      *
2090      * @return the number of bytes between the current {@code readerIndex}
2091      *         and the first occurrence if found. {@code -1} otherwise.
2092      *
2093      * @throws IndexOutOfBoundsException
2094      *         if {@code length} is greater than {@code this.readableBytes}
2095      */
2096     public abstract int bytesBefore(int length, byte value);
2097 
2098     /**
2099      * Locates the first occurrence of the specified {@code value} in this
2100      * buffer.  The search starts from the specified {@code index} (inclusive)
2101      * and lasts for the specified {@code length}.
2102      * <p>
2103      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2104      * this buffer.
2105      *
2106      * @return the number of bytes between the specified {@code index}
2107      *         and the first occurrence if found. {@code -1} otherwise.
2108      *
2109      * @throws IndexOutOfBoundsException
2110      *         if {@code index + length} is greater than {@code this.capacity}
2111      */
2112     public abstract int bytesBefore(int index, int length, byte value);
2113 
2114     /**
2115      * Iterates over the readable bytes of this buffer with the specified {@code processor} in ascending order.
2116      *
2117      * @return {@code -1} if the processor iterated to or beyond the end of the readable bytes.
2118      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2119      */
2120     public abstract int forEachByte(ByteProcessor processor);
2121 
2122     /**
2123      * Iterates over the specified area of this buffer with the specified {@code processor} in ascending order.
2124      * (i.e. {@code index}, {@code (index + 1)},  .. {@code (index + length - 1)})
2125      *
2126      * @return {@code -1} if the processor iterated to or beyond the end of the specified area.
2127      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2128      */
2129     public abstract int forEachByte(int index, int length, ByteProcessor processor);
2130 
2131     /**
2132      * Iterates over the readable bytes of this buffer with the specified {@code processor} in descending order.
2133      *
2134      * @return {@code -1} if the processor iterated to or beyond the beginning of the readable bytes.
2135      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2136      */
2137     public abstract int forEachByteDesc(ByteProcessor processor);
2138 
2139     /**
2140      * Iterates over the specified area of this buffer with the specified {@code processor} in descending order.
2141      * (i.e. {@code (index + length - 1)}, {@code (index + length - 2)}, ... {@code index})
2142      *
2143      *
2144      * @return {@code -1} if the processor iterated to or beyond the beginning of the specified area.
2145      *         The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2146      */
2147     public abstract int forEachByteDesc(int index, int length, ByteProcessor processor);
2148 
2149     /**
2150      * Returns a copy of this buffer's readable bytes.  Modifying the content
2151      * of the returned buffer or this buffer does not affect each other at all.
2152      * This method is identical to {@code buf.copy(buf.readerIndex(), buf.readableBytes())}.
2153      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2154      * this buffer.
2155      */
2156     public abstract ByteBuf copy();
2157 
2158     /**
2159      * Returns a copy of this buffer's sub-region.  Modifying the content of
2160      * the returned buffer or this buffer does not affect each other at all.
2161      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2162      * this buffer.
2163      */
2164     public abstract ByteBuf copy(int index, int length);
2165 
2166     /**
2167      * Returns a slice of this buffer's readable bytes. Modifying the content
2168      * of the returned buffer or this buffer affects each other's content
2169      * while they maintain separate indexes and marks.  This method is
2170      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2171      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2172      * this buffer.
2173      * <p>
2174      * Also be aware that this method will NOT call {@link #retain()} and so the
2175      * reference count will NOT be increased.
2176      */
2177     public abstract ByteBuf slice();
2178 
2179     /**
2180      * Returns a retained slice of this buffer's readable bytes. Modifying the content
2181      * of the returned buffer or this buffer affects each other's content
2182      * while they maintain separate indexes and marks.  This method is
2183      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2184      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2185      * this buffer.
2186      * <p>
2187      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice()}.
2188      * This method behaves similarly to {@code slice().retain()} except that this method may return
2189      * a buffer implementation that produces less garbage.
2190      */
2191     public abstract ByteBuf retainedSlice();
2192 
2193     /**
2194      * Returns a slice of this buffer's sub-region. Modifying the content of
2195      * the returned buffer or this buffer affects each other's content while
2196      * they maintain separate indexes and marks.
2197      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2198      * this buffer.
2199      * <p>
2200      * Also be aware that this method will NOT call {@link #retain()} and so the
2201      * reference count will NOT be increased.
2202      */
2203     public abstract ByteBuf slice(int index, int length);
2204 
2205     /**
2206      * Returns a retained slice of this buffer's sub-region. Modifying the content of
2207      * the returned buffer or this buffer affects each other's content while
2208      * they maintain separate indexes and marks.
2209      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2210      * this buffer.
2211      * <p>
2212      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2213      * This method behaves similarly to {@code slice(...).retain()} except that this method may return
2214      * a buffer implementation that produces less garbage.
2215      */
2216     public abstract ByteBuf retainedSlice(int index, int length);
2217 
2218     /**
2219      * Returns a buffer which shares the whole region of this buffer.
2220      * Modifying the content of the returned buffer or this buffer affects
2221      * each other's content while they maintain separate indexes and marks.
2222      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2223      * this buffer.
2224      * <p>
2225      * The reader and writer marks will not be duplicated. Also be aware that this method will
2226      * NOT call {@link #retain()} and so the reference count will NOT be increased.
2227      * @return A buffer whose readable content is equivalent to the buffer returned by {@link #slice()}.
2228      * However this buffer will share the capacity of the underlying buffer, and therefore allows access to all of the
2229      * underlying content if necessary.
2230      */
2231     public abstract ByteBuf duplicate();
2232 
2233     /**
2234      * Returns a retained buffer which shares the whole region of this buffer.
2235      * Modifying the content of the returned buffer or this buffer affects
2236      * each other's content while they maintain separate indexes and marks.
2237      * This method is identical to {@code buf.slice(0, buf.capacity())}.
2238      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2239      * this buffer.
2240      * <p>
2241      * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2242      * This method behaves similarly to {@code duplicate().retain()} except that this method may return
2243      * a buffer implementation that produces less garbage.
2244      */
2245     public abstract ByteBuf retainedDuplicate();
2246 
2247     /**
2248      * Returns the maximum number of NIO {@link ByteBuffer}s that consist this buffer.  Note that {@link #nioBuffers()}
2249      * or {@link #nioBuffers(int, int)} might return a less number of {@link ByteBuffer}s.
2250      *
2251      * @return {@code -1} if this buffer has no underlying {@link ByteBuffer}.
2252      *         the number of the underlying {@link ByteBuffer}s if this buffer has at least one underlying
2253      *         {@link ByteBuffer}.  Note that this method does not return {@code 0} to avoid confusion.
2254      *
2255      * @see #nioBuffer()
2256      * @see #nioBuffer(int, int)
2257      * @see #nioBuffers()
2258      * @see #nioBuffers(int, int)
2259      */
2260     public abstract int nioBufferCount();
2261 
2262     /**
2263      * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}. The returned buffer
2264      * either share or contains the copied content of this buffer, while changing the position
2265      * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2266      * This method is identical to {@code buf.nioBuffer(buf.readerIndex(), buf.readableBytes())}.
2267      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2268      * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2269      * is a dynamic buffer and it adjusted its capacity.
2270      *
2271      * @throws UnsupportedOperationException
2272      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2273      *
2274      * @see #nioBufferCount()
2275      * @see #nioBuffers()
2276      * @see #nioBuffers(int, int)
2277      */
2278     public abstract ByteBuffer nioBuffer();
2279 
2280     /**
2281      * Exposes this buffer's sub-region as an NIO {@link ByteBuffer}. The returned buffer
2282      * either share or contains the copied content of this buffer, while changing the position
2283      * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2284      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2285      * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2286      * is a dynamic buffer and it adjusted its capacity.
2287      *
2288      * @throws UnsupportedOperationException
2289      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2290      *
2291      * @see #nioBufferCount()
2292      * @see #nioBuffers()
2293      * @see #nioBuffers(int, int)
2294      */
2295     public abstract ByteBuffer nioBuffer(int index, int length);
2296 
2297     /**
2298      * Internal use only: Exposes the internal NIO buffer.
2299      */
2300     public abstract ByteBuffer internalNioBuffer(int index, int length);
2301 
2302     /**
2303      * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}'s. The returned buffer
2304      * either share or contains the copied content of this buffer, while changing the position
2305      * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2306      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2307      * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2308      * is a dynamic buffer and it adjusted its capacity.
2309      *
2310      *
2311      * @throws UnsupportedOperationException
2312      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2313      *
2314      * @see #nioBufferCount()
2315      * @see #nioBuffer()
2316      * @see #nioBuffer(int, int)
2317      */
2318     public abstract ByteBuffer[] nioBuffers();
2319 
2320     /**
2321      * Exposes this buffer's bytes as an NIO {@link ByteBuffer}'s for the specified index and length
2322      * The returned buffer either share or contains the copied content of this buffer, while changing
2323      * the position and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2324      * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer. Please note that the
2325      * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2326      * buffer and it adjusted its capacity.
2327      *
2328      * @throws UnsupportedOperationException
2329      *         if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2330      *
2331      * @see #nioBufferCount()
2332      * @see #nioBuffer()
2333      * @see #nioBuffer(int, int)
2334      */
2335     public abstract ByteBuffer[] nioBuffers(int index, int length);
2336 
2337     /**
2338      * Returns {@code true} if and only if this buffer has a backing byte array.
2339      * If this method returns true, you can safely call {@link #array()} and
2340      * {@link #arrayOffset()}.
2341      */
2342     public abstract boolean hasArray();
2343 
2344     /**
2345      * Returns the backing byte array of this buffer.
2346      *
2347      * @throws UnsupportedOperationException
2348      *         if there no accessible backing byte array
2349      */
2350     public abstract byte[] array();
2351 
2352     /**
2353      * Returns the offset of the first byte within the backing byte array of
2354      * this buffer.
2355      *
2356      * @throws UnsupportedOperationException
2357      *         if there no accessible backing byte array
2358      */
2359     public abstract int arrayOffset();
2360 
2361     /**
2362      * Returns {@code true} if and only if this buffer has a reference to the low-level memory address that points
2363      * to the backing data.
2364      */
2365     public abstract boolean hasMemoryAddress();
2366 
2367     /**
2368      * Returns the low-level memory address that point to the first byte of ths backing data.
2369      *
2370      * @throws UnsupportedOperationException
2371      *         if this buffer does not support accessing the low-level memory address
2372      */
2373     public abstract long memoryAddress();
2374 
2375     /**
2376      * Decodes this buffer's readable bytes into a string with the specified
2377      * character set name.  This method is identical to
2378      * {@code buf.toString(buf.readerIndex(), buf.readableBytes(), charsetName)}.
2379      * This method does not modify {@code readerIndex} or {@code writerIndex} of
2380      * this buffer.
2381      *
2382      * @throws UnsupportedCharsetException
2383      *         if the specified character set name is not supported by the
2384      *         current VM
2385      */
2386     public abstract String toString(Charset charset);
2387 
2388     /**
2389      * Decodes this buffer's sub-region into a string with the specified
2390      * character set.  This method does not modify {@code readerIndex} or
2391      * {@code writerIndex} of this buffer.
2392      */
2393     public abstract String toString(int index, int length, Charset charset);
2394 
2395     /**
2396      * Returns a hash code which was calculated from the content of this
2397      * buffer.  If there's a byte array which is
2398      * {@linkplain #equals(Object) equal to} this array, both arrays should
2399      * return the same value.
2400      */
2401     @Override
2402     public abstract int hashCode();
2403 
2404     /**
2405      * Determines if the content of the specified buffer is identical to the
2406      * content of this array.  'Identical' here means:
2407      * <ul>
2408      * <li>the size of the contents of the two buffers are same and</li>
2409      * <li>every single byte of the content of the two buffers are same.</li>
2410      * </ul>
2411      * Please note that it does not compare {@link #readerIndex()} nor
2412      * {@link #writerIndex()}.  This method also returns {@code false} for
2413      * {@code null} and an object which is not an instance of
2414      * {@link ByteBuf} type.
2415      */
2416     @Override
2417     public abstract boolean equals(Object obj);
2418 
2419     /**
2420      * Compares the content of the specified buffer to the content of this
2421      * buffer. Comparison is performed in the same manner with the string
2422      * comparison functions of various languages such as {@code strcmp},
2423      * {@code memcmp} and {@link String#compareTo(String)}.
2424      */
2425     @Override
2426     public abstract int compareTo(ByteBuf buffer);
2427 
2428     /**
2429      * Returns the string representation of this buffer.  This method does not
2430      * necessarily return the whole content of the buffer but returns
2431      * the values of the key properties such as {@link #readerIndex()},
2432      * {@link #writerIndex()} and {@link #capacity()}.
2433      */
2434     @Override
2435     public abstract String toString();
2436 
2437     @Override
2438     public abstract ByteBuf retain(int increment);
2439 
2440     @Override
2441     public abstract ByteBuf retain();
2442 
2443     @Override
2444     public abstract ByteBuf touch();
2445 
2446     @Override
2447     public abstract ByteBuf touch(Object hint);
2448 }