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