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