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 org.jboss.netty.buffer;
    17
    18  import java.io.IOException;
    19  import java.io.InputStream;
    20  import java.io.OutputStream;
    21  import java.nio.ByteBuffer;
    22  import java.nio.ByteOrder;
    23  import java.nio.channels.GatheringByteChannel;
    24  import java.nio.channels.ScatteringByteChannel;
    25  import java.nio.charset.Charset;
    26  import java.nio.charset.UnsupportedCharsetException;
    27
    28  /**
    29   * A random and sequential accessible sequence of zero or more bytes (octets).
    30   * This interface provides an abstract view for one or more primitive byte
    31   * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}.
    32   *
    33   * <h3>Creation of a buffer</h3>
    34   *
    35   * It is recommended to create a new buffer using the helper methods in
    36   * {@link ChannelBuffers} rather than calling an individual implementation's
    37   * constructor.
    38   *
    39   * <h3>Random Access Indexing</h3>
    40   *
    41   * Just like an ordinary primitive byte array, {@link ChannelBuffer} uses
    42   * <a href="http://en.wikipedia.org/wiki/Zero-based_numbering">zero-based indexing</a>.
    43   * It means the index of the first byte is always {@code 0} and the index of the last byte is
    44   * always {@link #capacity() capacity - 1}.  For example, to iterate all bytes of a buffer, you
    45   * can do the following, regardless of its internal implementation:
    46   *
    47   * <pre>
    48   * {@link ChannelBuffer} buffer = ...;
    49   * for (int i = 0; i &lt; buffer.capacity(); i ++) {
    50   *     byte b = buffer.getByte(i);
    51   *     System.out.println((char) b);
    52   * }
    53   * </pre>
    54   *
    55   * <h3>Sequential Access Indexing</h3>
    56   *
    57   * {@link ChannelBuffer} provides two pointer variables to support sequential
    58   * read and write operations - {@link #readerIndex() readerIndex} for a read
    59   * operation and {@link #writerIndex() writerIndex} for a write operation
    60   * respectively.  The following diagram shows how a buffer is segmented into
    61   * three areas by the two pointers:
    62   *
    63   * <pre>
    64   *      +-------------------+------------------+------------------+
    65   *      | discardable bytes |  readable bytes  |  writable bytes  |
    66   *      |                   |     (CONTENT)    |                  |
    67   *      +-------------------+------------------+------------------+
    68   *      |                   |                  |                  |
    69   *      0      <=      readerIndex   <=   writerIndex    <=    capacity
    70   * </pre>
    71   *
    72   * <h4>Readable bytes (the actual content)</h4>
    73   *
    74   * This segment is where the actual data is stored.  Any operation whose name
    75   * starts with {@code read} or {@code skip} will get or skip the data at the
    76   * current {@link #readerIndex() readerIndex} and increase it by the number of
    77   * read bytes.  If the argument of the read operation is also a
    78   * {@link ChannelBuffer} and no destination index is specified, the specified
    79   * buffer's {@link #readerIndex() readerIndex} is increased together.
    80   * <p>
    81   * If there's not enough content left, {@link IndexOutOfBoundsException} is
    82   * raised.  The default value of newly allocated, wrapped or copied buffer's
    83   * {@link #readerIndex() readerIndex} is {@code 0}.
    84   *
    85   * <pre>
    86   * // Iterates the readable bytes of a buffer.
    87   * {@link ChannelBuffer} buffer = ...;
    88   * while (buffer.readable()) {
    89   *     System.out.println(buffer.readByte());
    90   * }
    91   * </pre>
    92   *
    93   * <h4>Writable bytes</h4>
    94   *
    95   * This segment is a undefined space which needs to be filled.  Any operation
    96   * whose name ends with {@code write} will write the data at the current
    97   * {@link #writerIndex() writerIndex} and increase it by the number of written
    98   * bytes.  If the argument of the write operation is also a {@link ChannelBuffer},
    99   * and no source index is specified, the specified buffer's
    100  * {@link #readerIndex() readerIndex} is increased together.
    101  * <p>
    102  * If there's not enough writable bytes left, {@link IndexOutOfBoundsException}
    103  * is raised.  The default value of newly allocated buffer's
    104  * {@link #writerIndex() writerIndex} is {@code 0}.  The default value of
    105  * wrapped or copied buffer's {@link #writerIndex() writerIndex} is the
    106  * {@link #capacity() capacity} of the buffer.
    107  *
    108  * <pre>
    109  * // Fills the writable bytes of a buffer with random integers.
    110  * {@link ChannelBuffer} buffer = ...;
    111  * while (buffer.writableBytes() >= 4) {
    112  *     buffer.writeInt(random.nextInt());
    113  * }
    114  * </pre>
    115  *
    116  * <h4>Discardable bytes</h4>
    117  *
    118  * This segment contains the bytes which were read already by a read operation.
    119  * Initially, the size of this segment is {@code 0}, but its size increases up
    120  * to the {@link #writerIndex() writerIndex} as read operations are executed.
    121  * The read bytes can be discarded by calling {@link #discardReadBytes()} to
    122  * reclaim unused area as depicted by the following diagram:
    123  *
    124  * <pre>
    125  *  BEFORE discardReadBytes()
    126  *
    127  *      +-------------------+------------------+------------------+
    128  *      | discardable bytes |  readable bytes  |  writable bytes  |
    129  *      +-------------------+------------------+------------------+
    130  *      |                   |                  |                  |
    131  *      0      <=      readerIndex   <=   writerIndex    <=    capacity
    132  *
    133  *
    134  *  AFTER discardReadBytes()
    135  *
    136  *      +------------------+--------------------------------------+
    137  *      |  readable bytes  |    writable bytes (got more space)   |
    138  *      +------------------+--------------------------------------+
    139  *      |                  |                                      |
    140  * readerIndex (0) <= writerIndex (decreased)        <=        capacity
    141  * </pre>
    142  *
    143  * Please note that there is no guarantee about the content of writable bytes
    144  * after calling {@link #discardReadBytes()}.  The writable bytes will not be
    145  * moved in most cases and could even be filled with completely different data
    146  * depending on the underlying buffer implementation.
    147  *
    148  * <h4>Clearing the buffer indexes</h4>
    149  *
    150  * You can set both {@link #readerIndex() readerIndex} and
    151  * {@link #writerIndex() writerIndex} to {@code 0} by calling {@link #clear()}.
    152  * It does not clear the buffer content (e.g. filling with {@code 0}) but just
    153  * clears the two pointers.  Please also note that the semantic of this
    154  * operation is different from {@link ByteBuffer#clear()}.
    155  *
    156  * <pre>
    157  *  BEFORE clear()
    158  *
    159  *      +-------------------+------------------+------------------+
    160  *      | discardable bytes |  readable bytes  |  writable bytes  |
    161  *      +-------------------+------------------+------------------+
    162  *      |                   |                  |                  |
    163  *      0      <=      readerIndex   <=   writerIndex    <=    capacity
    164  *
    165  *
    166  *  AFTER clear()
    167  *
    168  *      +---------------------------------------------------------+
    169  *      |             writable bytes (got more space)             |
    170  *      +---------------------------------------------------------+
    171  *      |                                                         |
    172  *      0 = readerIndex = writerIndex            <=            capacity
    173  * </pre>
    174  *
    175  * <h3>Search operations</h3>
    176  *
    177  * Various {@link #indexOf(int, int, byte)} methods help you locate an index of
    178  * a value which meets a certain criteria.  Complicated dynamic sequential
    179  * search can be done with {@link ChannelBufferIndexFinder} as well as simple
    180  * static single byte search.
    181  * <p>
    182  * If you are decoding variable length data such as NUL-terminated string, you
    183  * will find {@link #bytesBefore(byte)} also useful.
    184  *
    185  * <h3>Mark and reset</h3>
    186  *
    187  * There are two marker indexes in every buffer. One is for storing
    188  * {@link #readerIndex() readerIndex} and the other is for storing
    189  * {@link #writerIndex() writerIndex}.  You can always reposition one of the
    190  * two indexes by calling a reset method.  It works in a similar fashion to
    191  * the mark and reset methods in {@link InputStream} except that there's no
    192  * {@code readlimit}.
    193  *
    194  * <h3>Derived buffers</h3>
    195  *
    196  * You can create a view of an existing buffer by calling either
    197  * {@link #duplicate()}, {@link #slice()} or {@link #slice(int, int)}.
    198  * A derived buffer will have an independent {@link #readerIndex() readerIndex},
    199  * {@link #writerIndex() writerIndex} and marker indexes, while it shares
    200  * other internal data representation, just like a NIO buffer does.
    201  * <p>
    202  * In case a completely fresh copy of an existing buffer is required, please
    203  * call {@link #copy()} method instead.
    204  *
    205  * <h3>Conversion to existing JDK types</h3>
    206  *
    207  * <h4>Byte array</h4>
    208  *
    209  * If a {@link ChannelBuffer} is backed by a byte array (i.e. {@code byte[]}),
    210  * you can access it directly via the {@link #array()} method.  To determine
    211  * if a buffer is backed by a byte array, {@link #hasArray()} should be used.
    212  *
    213  * <h4>NIO Buffers</h4>
    214  *
    215  * Various {@link #toByteBuffer()} and {@link #toByteBuffers()} methods convert
    216  * a {@link ChannelBuffer} into one or more NIO buffers.  These methods avoid
    217  * buffer allocation and memory copy whenever possible, but there's no
    218  * guarantee that memory copy will not be involved.
    219  *
    220  * <h4>Strings</h4>
    221  *
    222  * Various {@link #toString(String)} methods convert a {@link ChannelBuffer}
    223  * into a {@link String}.  Please note that {@link #toString()} is not a
    224  * conversion method.
    225  *
    226  * <h4>I/O Streams</h4>
    227  *
    228  * Please refer to {@link ChannelBufferInputStream} and
    229  * {@link ChannelBufferOutputStream}.
    230  *
    231  * @apiviz.landmark
    232  */
    233 public interface ChannelBuffer extends Comparable<ChannelBuffer> {
    234
    235     /**
    236      * Returns the factory which creates a {@link ChannelBuffer} whose
    237      * type and default {@link ByteOrder} are same with this buffer.
    238      */
    239     ChannelBufferFactory factory();
    240
    241     /**
    242      * Returns the number of bytes (octets) this buffer can contain.
    243      */
    244     int capacity();
    245
    246     /**
    247      * Returns the <a href="http://en.wikipedia.org/wiki/Endianness">endianness</a>
    248      * of this buffer.
    249      */
    250     ByteOrder order();
    251
    252     /**
    253      * Returns {@code true} if and only if this buffer is backed by an
    254      * NIO direct buffer.
    255      */
    256     boolean isDirect();
    257
    258     /**
    259      * Returns the {@code readerIndex} of this buffer.
    260      */
    261     int readerIndex();
    262
    263     /**
    264      * Sets the {@code readerIndex} of this buffer.
    265      *
    266      * @throws IndexOutOfBoundsException
    267      *         if the specified {@code readerIndex} is
    268      *            less than {@code 0} or
    269      *            greater than {@code this.writerIndex}
    270      */
    271     void readerIndex(int readerIndex);
    272
    273     /**
    274      * Returns the {@code writerIndex} of this buffer.
    275      */
    276     int writerIndex();
    277
    278     /**
    279      * Sets the {@code writerIndex} of this buffer.
    280      *
    281      * @throws IndexOutOfBoundsException
    282      *         if the specified {@code writerIndex} is
    283      *            less than {@code this.readerIndex} or
    284      *            greater than {@code this.capacity}
    285      */
    286     void writerIndex(int writerIndex);
    287
    288     /**
    289      * Sets the {@code readerIndex} and {@code writerIndex} of this buffer
    290      * in one shot.  This method is useful when you have to worry about the
    291      * invocation order of {@link #readerIndex(int)} and {@link #writerIndex(int)}
    292      * methods.  For example, the following code will fail:
    293      *
    294      * <pre>
    295      * // Create a buffer whose readerIndex, writerIndex and capacity are
    296      * // 0, 0 and 8 respectively.
    297      * {@link ChannelBuffer} buf = {@link ChannelBuffers}.buffer(8);
    298      *
    299      * // IndexOutOfBoundsException is thrown because the specified
    300      * // readerIndex (2) cannot be greater than the current writerIndex (0).
    301      * buf.readerIndex(2);
    302      * buf.writerIndex(4);
    303      * </pre>
    304      *
    305      * The following code will also fail:
    306      *
    307      * <pre>
    308      * // Create a buffer whose readerIndex, writerIndex and capacity are
    309      * // 0, 8 and 8 respectively.
    310      * {@link ChannelBuffer} buf = {@link ChannelBuffers}.wrappedBuffer(new byte[8]);
    311      *
    312      * // readerIndex becomes 8.
    313      * buf.readLong();
    314      *
    315      * // IndexOutOfBoundsException is thrown because the specified
    316      * // writerIndex (4) cannot be less than the current readerIndex (8).
    317      * buf.writerIndex(4);
    318      * buf.readerIndex(2);
    319      * </pre>
    320      *
    321      * By contrast, {@link #setIndex(int, int)} guarantees that it never
    322      * throws an {@link IndexOutOfBoundsException} as long as the specified
    323      * indexes meet basic constraints, regardless what the current index
    324      * values of the buffer are:
    325      *
    326      * <pre>
    327      * // No matter what the current state of the buffer is, the following
    328      * // call always succeeds as long as the capacity of the buffer is not
    329      * // less than 4.
    330      * buf.setIndex(2, 4);
    331      * </pre>
    332      *
    333      * @throws IndexOutOfBoundsException
    334      *         if the specified {@code readerIndex} is less than 0,
    335      *         if the specified {@code writerIndex} is less than the specified
    336      *         {@code readerIndex} or if the specified {@code writerIndex} is
    337      *         greater than {@code this.capacity}
    338      */
    339     void setIndex(int readerIndex, int writerIndex);
    340
    341     /**
    342      * Returns the number of readable bytes which is equal to
    343      * {@code (this.writerIndex - this.readerIndex)}.
    344      */
    345     int readableBytes();
    346
    347     /**
    348      * Returns the number of writable bytes which is equal to
    349      * {@code (this.capacity - this.writerIndex)}.
    350      */
    351     int writableBytes();
    352
    353     /**
    354      * Returns {@code true}
    355      * if and only if {@code (this.writerIndex - this.readerIndex)} is greater
    356      * than {@code 0}.
    357      */
    358     boolean readable();
    359
    360     /**
    361      * Returns {@code true}
    362      * if and only if {@code (this.capacity - this.writerIndex)} is greater
    363      * than {@code 0}.
    364      */
    365     boolean writable();
    366
    367     /**
    368      * Sets the {@code readerIndex} and {@code writerIndex} of this buffer to
    369      * {@code 0}.
    370      * This method is identical to {@link #setIndex(int, int) setIndex(0, 0)}.
    371      * <p>
    372      * Please note that the behavior of this method is different
    373      * from that of NIO buffer, which sets the {@code limit} to
    374      * the {@code capacity} of the buffer.
    375      */
    376     void clear();
    377
    378     /**
    379      * Marks the current {@code readerIndex} in this buffer.  You can
    380      * reposition the current {@code readerIndex} to the marked
    381      * {@code readerIndex} by calling {@link #resetReaderIndex()}.
    382      * The initial value of the marked {@code readerIndex} is {@code 0}.
    383      */
    384     void markReaderIndex();
    385
    386     /**
    387      * Repositions the current {@code readerIndex} to the marked
    388      * {@code readerIndex} in this buffer.
    389      *
    390      * @throws IndexOutOfBoundsException
    391      *         if the current {@code writerIndex} is less than the marked
    392      *         {@code readerIndex}
    393      */
    394     void resetReaderIndex();
    395
    396     /**
    397      * Marks the current {@code writerIndex} in this buffer.  You can
    398      * reposition the current {@code writerIndex} to the marked
    399      * {@code writerIndex} by calling {@link #resetWriterIndex()}.
    400      * The initial value of the marked {@code writerIndex} is {@code 0}.
    401      */
    402     void markWriterIndex();
    403
    404     /**
    405      * Repositions the current {@code writerIndex} to the marked
    406      * {@code writerIndex} in this buffer.
    407      *
    408      * @throws IndexOutOfBoundsException
    409      *         if the current {@code readerIndex} is greater than the marked
    410      *         {@code writerIndex}
    411      */
    412     void resetWriterIndex();
    413
    414     /**
    415      * Discards the bytes between the 0th index and {@code readerIndex}.
    416      * It moves the bytes between {@code readerIndex} and {@code writerIndex}
    417      * to the 0th index, and sets {@code readerIndex} and {@code writerIndex}
    418      * to {@code 0} and {@code oldWriterIndex - oldReaderIndex} respectively.
    419      * <p>
    420      * Please refer to the class documentation for more detailed explanation.
    421      */
    422     void discardReadBytes();
    423
    424     /**
    425      * Makes sure the number of {@linkplain #writableBytes() the writable bytes}
    426      * is equal to or greater than the specified value.  If there is enough
    427      * writable bytes in this buffer, this method returns with no side effect.
    428      * Otherwise:
    429      * <ul>
    430      * <li>a non-dynamic buffer will throw an {@link IndexOutOfBoundsException}.</li>
    431      * <li>a dynamic buffer will expand its capacity so that the number of the
    432      *     {@link #writableBytes() writable bytes} becomes equal to or greater
    433      *     than the specified value. The expansion involves the reallocation of
    434      *     the internal buffer and consequently memory copy.</li>
    435      * </ul>
    436      *
    437      * @param writableBytes
    438      *        the expected minimum number of writable bytes
    439      * @throws IndexOutOfBoundsException
    440      *         if {@linkplain #writableBytes() the writable bytes} of this
    441      *         buffer is less than the specified value and if this buffer is
    442      *         not a dynamic buffer
    443      */
    444     void ensureWritableBytes(int writableBytes);
    445
    446     /**
    447      * Gets a byte at the specified absolute {@code index} in this buffer.
    448      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    449      * this buffer.
    450      *
    451      * @throws IndexOutOfBoundsException
    452      *         if the specified {@code index} is less than {@code 0} or
    453      *         {@code index + 1} is greater than {@code this.capacity}
    454      */
    455     byte  getByte(int index);
    456
    457     /**
    458      * Gets an unsigned byte at the specified absolute {@code index} in this
    459      * buffer.  This method does not modify {@code readerIndex} or
    460      * {@code writerIndex} of this buffer.
    461      *
    462      * @throws IndexOutOfBoundsException
    463      *         if the specified {@code index} is less than {@code 0} or
    464      *         {@code index + 1} is greater than {@code this.capacity}
    465      */
    466     short getUnsignedByte(int index);
    467
    468     /**
    469      * Gets a 16-bit short integer at the specified absolute {@code index} in
    470      * this buffer.  This method does not modify {@code readerIndex} or
    471      * {@code writerIndex} of this buffer.
    472      *
    473      * @throws IndexOutOfBoundsException
    474      *         if the specified {@code index} is less than {@code 0} or
    475      *         {@code index + 2} is greater than {@code this.capacity}
    476      */
    477     short getShort(int index);
    478
    479     /**
    480      * Gets an unsigned 16-bit short integer at the specified absolute
    481      * {@code index} in this buffer.  This method does not modify
    482      * {@code readerIndex} or {@code writerIndex} of this buffer.
    483      *
    484      * @throws IndexOutOfBoundsException
    485      *         if the specified {@code index} is less than {@code 0} or
    486      *         {@code index + 2} is greater than {@code this.capacity}
    487      */
    488     int getUnsignedShort(int index);
    489
    490     /**
    491      * Gets a 24-bit medium integer at the specified absolute {@code index} in
    492      * this buffer.  This method does not modify {@code readerIndex} or
    493      * {@code writerIndex} of this buffer.
    494      *
    495      * @throws IndexOutOfBoundsException
    496      *         if the specified {@code index} is less than {@code 0} or
    497      *         {@code index + 3} is greater than {@code this.capacity}
    498      */
    499     int   getMedium(int index);
    500
    501     /**
    502      * Gets an unsigned 24-bit medium integer at the specified absolute
    503      * {@code index} in this buffer.  This method does not modify
    504      * {@code readerIndex} or {@code writerIndex} of this buffer.
    505      *
    506      * @throws IndexOutOfBoundsException
    507      *         if the specified {@code index} is less than {@code 0} or
    508      *         {@code index + 3} is greater than {@code this.capacity}
    509      */
    510     int   getUnsignedMedium(int index);
    511
    512     /**
    513      * Gets a 32-bit integer at the specified absolute {@code index} in
    514      * this buffer.  This method does not modify {@code readerIndex} or
    515      * {@code writerIndex} of this buffer.
    516      *
    517      * @throws IndexOutOfBoundsException
    518      *         if the specified {@code index} is less than {@code 0} or
    519      *         {@code index + 4} is greater than {@code this.capacity}
    520      */
    521     int   getInt(int index);
    522
    523     /**
    524      * Gets an unsigned 32-bit integer at the specified absolute {@code index}
    525      * in this buffer.  This method does not modify {@code readerIndex} or
    526      * {@code writerIndex} of this buffer.
    527      *
    528      * @throws IndexOutOfBoundsException
    529      *         if the specified {@code index} is less than {@code 0} or
    530      *         {@code index + 4} is greater than {@code this.capacity}
    531      */
    532     long  getUnsignedInt(int index);
    533
    534     /**
    535      * Gets a 64-bit long integer at the specified absolute {@code index} in
    536      * this buffer.  This method does not modify {@code readerIndex} or
    537      * {@code writerIndex} of this buffer.
    538      *
    539      * @throws IndexOutOfBoundsException
    540      *         if the specified {@code index} is less than {@code 0} or
    541      *         {@code index + 8} is greater than {@code this.capacity}
    542      */
    543     long  getLong(int index);
    544
    545     /**
    546      * Gets a 2-byte UTF-16 character at the specified absolute
    547      * {@code index} in this buffer.  This method does not modify
    548      * {@code readerIndex} or {@code writerIndex} of this buffer.
    549      *
    550      * @throws IndexOutOfBoundsException
    551      *         if the specified {@code index} is less than {@code 0} or
    552      *         {@code index + 2} is greater than {@code this.capacity}
    553      */
    554     char  getChar(int index);
    555
    556     /**
    557      * Gets a 32-bit floating point number at the specified absolute
    558      * {@code index} in this buffer.  This method does not modify
    559      * {@code readerIndex} or {@code writerIndex} of this buffer.
    560      *
    561      * @throws IndexOutOfBoundsException
    562      *         if the specified {@code index} is less than {@code 0} or
    563      *         {@code index + 4} is greater than {@code this.capacity}
    564      */
    565     float getFloat(int index);
    566
    567     /**
    568      * Gets a 64-bit floating point number at the specified absolute
    569      * {@code index} in this buffer.  This method does not modify
    570      * {@code readerIndex} or {@code writerIndex} of this buffer.
    571      *
    572      * @throws IndexOutOfBoundsException
    573      *         if the specified {@code index} is less than {@code 0} or
    574      *         {@code index + 8} is greater than {@code this.capacity}
    575      */
    576     double getDouble(int index);
    577
    578     /**
    579      * Transfers this buffer's data to the specified destination starting at
    580      * the specified absolute {@code index} until the destination becomes
    581      * non-writable.  This method is basically same with
    582      * {@link #getBytes(int, ChannelBuffer, int, int)}, except that this
    583      * method increases the {@code writerIndex} of the destination by the
    584      * number of the transferred bytes while
    585      * {@link #getBytes(int, ChannelBuffer, int, int)} does not.
    586      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    587      * the source buffer (i.e. {@code this}).
    588      *
    589      * @throws IndexOutOfBoundsException
    590      *         if the specified {@code index} is less than {@code 0} or
    591      *         if {@code index + dst.writableBytes} is greater than
    592      *            {@code this.capacity}
    593      */
    594     void  getBytes(int index, ChannelBuffer dst);
    595
    596     /**
    597      * Transfers this buffer's data to the specified destination starting at
    598      * the specified absolute {@code index}.  This method is basically same
    599      * with {@link #getBytes(int, ChannelBuffer, int, int)}, except that this
    600      * method increases the {@code writerIndex} of the destination by the
    601      * number of the transferred bytes while
    602      * {@link #getBytes(int, ChannelBuffer, int, int)} does not.
    603      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    604      * the source buffer (i.e. {@code this}).
    605      *
    606      * @param length the number of bytes to transfer
    607      *
    608      * @throws IndexOutOfBoundsException
    609      *         if the specified {@code index} is less than {@code 0},
    610      *         if {@code index + length} is greater than
    611      *            {@code this.capacity}, or
    612      *         if {@code length} is greater than {@code dst.writableBytes}
    613      */
    614     void  getBytes(int index, ChannelBuffer dst, int length);
    615
    616     /**
    617      * Transfers this buffer's data to the specified destination starting at
    618      * the specified absolute {@code index}.
    619      * This method does not modify {@code readerIndex} or {@code writerIndex}
    620      * of both the source (i.e. {@code this}) and the destination.
    621      *
    622      * @param dstIndex the first index of the destination
    623      * @param length   the number of bytes to transfer
    624      *
    625      * @throws IndexOutOfBoundsException
    626      *         if the specified {@code index} is less than {@code 0},
    627      *         if the specified {@code dstIndex} is less than {@code 0},
    628      *         if {@code index + length} is greater than
    629      *            {@code this.capacity}, or
    630      *         if {@code dstIndex + length} is greater than
    631      *            {@code dst.capacity}
    632      */
    633     void  getBytes(int index, ChannelBuffer dst, int dstIndex, int length);
    634
    635     /**
    636      * Transfers this buffer's data to the specified destination starting at
    637      * the specified absolute {@code index}.
    638      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    639      * this buffer
    640      *
    641      * @throws IndexOutOfBoundsException
    642      *         if the specified {@code index} is less than {@code 0} or
    643      *         if {@code index + dst.length} is greater than
    644      *            {@code this.capacity}
    645      */
    646     void  getBytes(int index, byte[] dst);
    647
    648     /**
    649      * Transfers this buffer's data to the specified destination starting at
    650      * the specified absolute {@code index}.
    651      * This method does not modify {@code readerIndex} or {@code writerIndex}
    652      * of this buffer.
    653      *
    654      * @param dstIndex the first index of the destination
    655      * @param length   the number of bytes to transfer
    656      *
    657      * @throws IndexOutOfBoundsException
    658      *         if the specified {@code index} is less than {@code 0},
    659      *         if the specified {@code dstIndex} is less than {@code 0},
    660      *         if {@code index + length} is greater than
    661      *            {@code this.capacity}, or
    662      *         if {@code dstIndex + length} is greater than
    663      *            {@code dst.length}
    664      */
    665     void  getBytes(int index, byte[] dst, int dstIndex, int length);
    666
    667     /**
    668      * Transfers this buffer's data to the specified destination starting at
    669      * the specified absolute {@code index} until the destination's position
    670      * reaches its limit.
    671      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    672      * this buffer while the destination's {@code position} will be increased.
    673      *
    674      * @throws IndexOutOfBoundsException
    675      *         if the specified {@code index} is less than {@code 0} or
    676      *         if {@code index + dst.remaining()} is greater than
    677      *            {@code this.capacity}
    678      */
    679     void  getBytes(int index, ByteBuffer dst);
    680
    681     /**
    682      * Transfers this buffer's data to the specified stream starting at the
    683      * specified absolute {@code index}.
    684      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    685      * this buffer.
    686      *
    687      * @param length the number of bytes to transfer
    688      *
    689      * @throws IndexOutOfBoundsException
    690      *         if the specified {@code index} is less than {@code 0} or
    691      *         if {@code index + length} is greater than
    692      *            {@code this.capacity}
    693      * @throws IOException
    694      *         if the specified stream threw an exception during I/O
    695      */
    696     void  getBytes(int index, OutputStream out, int length) throws IOException;
    697
    698     /**
    699      * Transfers this buffer's data to the specified channel starting at the
    700      * specified absolute {@code index}.
    701      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    702      * this buffer.
    703      *
    704      * @param length the maximum number of bytes to transfer
    705      *
    706      * @return the actual number of bytes written out to the specified channel
    707      *
    708      * @throws IndexOutOfBoundsException
    709      *         if the specified {@code index} is less than {@code 0} or
    710      *         if {@code index + length} is greater than
    711      *            {@code this.capacity}
    712      * @throws IOException
    713      *         if the specified channel threw an exception during I/O
    714      */
    715     int   getBytes(int index, GatheringByteChannel out, int length) throws IOException;
    716
    717     /**
    718      * Sets the specified byte at the specified absolute {@code index} in this
    719      * buffer.  The 24 high-order bits of the specified value are ignored.
    720      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    721      * this buffer.
    722      *
    723      * @throws IndexOutOfBoundsException
    724      *         if the specified {@code index} is less than {@code 0} or
    725      *         {@code index + 1} is greater than {@code this.capacity}
    726      */
    727     void setByte(int index, int   value);
    728
    729     /**
    730      * Sets the specified 16-bit short integer at the specified absolute
    731      * {@code index} in this buffer.  The 16 high-order bits of the specified
    732      * value are ignored.
    733      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    734      * this buffer.
    735      *
    736      * @throws IndexOutOfBoundsException
    737      *         if the specified {@code index} is less than {@code 0} or
    738      *         {@code index + 2} is greater than {@code this.capacity}
    739      */
    740     void setShort(int index, int value);
    741
    742     /**
    743      * Sets the specified 24-bit medium integer at the specified absolute
    744      * {@code index} in this buffer.  Please note that the most significant
    745      * byte is ignored in the specified value.
    746      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    747      * this buffer.
    748      *
    749      * @throws IndexOutOfBoundsException
    750      *         if the specified {@code index} is less than {@code 0} or
    751      *         {@code index + 3} is greater than {@code this.capacity}
    752      */
    753     void setMedium(int index, int   value);
    754
    755     /**
    756      * Sets the specified 32-bit integer at the specified absolute
    757      * {@code index} in this buffer.
    758      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    759      * this buffer.
    760      *
    761      * @throws IndexOutOfBoundsException
    762      *         if the specified {@code index} is less than {@code 0} or
    763      *         {@code index + 4} is greater than {@code this.capacity}
    764      */
    765     void setInt(int index, int   value);
    766
    767     /**
    768      * Sets the specified 64-bit long integer at the specified absolute
    769      * {@code index} in this buffer.
    770      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    771      * this buffer.
    772      *
    773      * @throws IndexOutOfBoundsException
    774      *         if the specified {@code index} is less than {@code 0} or
    775      *         {@code index + 8} is greater than {@code this.capacity}
    776      */
    777     void setLong(int index, long  value);
    778
    779     /**
    780      * Sets the specified 2-byte UTF-16 character at the specified absolute
    781      * {@code index} in this buffer.
    782      * The 16 high-order bits of the specified value are ignored.
    783      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    784      * this buffer.
    785      *
    786      * @throws IndexOutOfBoundsException
    787      *         if the specified {@code index} is less than {@code 0} or
    788      *         {@code index + 2} is greater than {@code this.capacity}
    789      */
    790     void setChar(int index, int value);
    791
    792     /**
    793      * Sets the specified 32-bit floating-point number at the specified
    794      * absolute {@code index} in this buffer.
    795      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    796      * this buffer.
    797      *
    798      * @throws IndexOutOfBoundsException
    799      *         if the specified {@code index} is less than {@code 0} or
    800      *         {@code index + 4} is greater than {@code this.capacity}
    801      */
    802     void setFloat(int index, float value);
    803
    804     /**
    805      * Sets the specified 64-bit floating-point number at the specified
    806      * absolute {@code index} in this buffer.
    807      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    808      * this buffer.
    809      *
    810      * @throws IndexOutOfBoundsException
    811      *         if the specified {@code index} is less than {@code 0} or
    812      *         {@code index + 8} is greater than {@code this.capacity}
    813      */
    814     void setDouble(int index, double value);
    815
    816     /**
    817      * Transfers the specified source buffer's data to this buffer starting at
    818      * the specified absolute {@code index} until the source buffer becomes
    819      * unreadable.  This method is basically same with
    820      * {@link #setBytes(int, ChannelBuffer, int, int)}, except that this
    821      * method increases the {@code readerIndex} of the source buffer by
    822      * the number of the transferred bytes while
    823      * {@link #setBytes(int, ChannelBuffer, int, int)} does not.
    824      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    825      * the source buffer (i.e. {@code this}).
    826      *
    827      * @throws IndexOutOfBoundsException
    828      *         if the specified {@code index} is less than {@code 0} or
    829      *         if {@code index + src.readableBytes} is greater than
    830      *            {@code this.capacity}
    831      */
    832     void setBytes(int index, ChannelBuffer src);
    833
    834     /**
    835      * Transfers the specified source buffer's data to this buffer starting at
    836      * the specified absolute {@code index}.  This method is basically same
    837      * with {@link #setBytes(int, ChannelBuffer, int, int)}, except that this
    838      * method increases the {@code readerIndex} of the source buffer by
    839      * the number of the transferred bytes while
    840      * {@link #setBytes(int, ChannelBuffer, int, int)} does not.
    841      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    842      * the source buffer (i.e. {@code this}).
    843      *
    844      * @param length the number of bytes to transfer
    845      *
    846      * @throws IndexOutOfBoundsException
    847      *         if the specified {@code index} is less than {@code 0},
    848      *         if {@code index + length} is greater than
    849      *            {@code this.capacity}, or
    850      *         if {@code length} is greater than {@code src.readableBytes}
    851      */
    852     void setBytes(int index, ChannelBuffer src, int length);
    853
    854     /**
    855      * Transfers the specified source buffer's data to this buffer starting at
    856      * the specified absolute {@code index}.
    857      * This method does not modify {@code readerIndex} or {@code writerIndex}
    858      * of both the source (i.e. {@code this}) and the destination.
    859      *
    860      * @param srcIndex the first index of the source
    861      * @param length   the number of bytes to transfer
    862      *
    863      * @throws IndexOutOfBoundsException
    864      *         if the specified {@code index} is less than {@code 0},
    865      *         if the specified {@code srcIndex} is less than {@code 0},
    866      *         if {@code index + length} is greater than
    867      *            {@code this.capacity}, or
    868      *         if {@code srcIndex + length} is greater than
    869      *            {@code src.capacity}
    870      */
    871     void setBytes(int index, ChannelBuffer src, int srcIndex, int length);
    872
    873     /**
    874      * Transfers the specified source array's data to this buffer starting at
    875      * the specified absolute {@code index}.
    876      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    877      * this buffer.
    878      *
    879      * @throws IndexOutOfBoundsException
    880      *         if the specified {@code index} is less than {@code 0} or
    881      *         if {@code index + src.length} is greater than
    882      *            {@code this.capacity}
    883      */
    884     void setBytes(int index, byte[] src);
    885
    886     /**
    887      * Transfers the specified source array's data to this buffer starting at
    888      * the specified absolute {@code index}.
    889      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    890      * this buffer.
    891      *
    892      * @throws IndexOutOfBoundsException
    893      *         if the specified {@code index} is less than {@code 0},
    894      *         if the specified {@code srcIndex} is less than {@code 0},
    895      *         if {@code index + length} is greater than
    896      *            {@code this.capacity}, or
    897      *         if {@code srcIndex + length} is greater than {@code src.length}
    898      */
    899     void setBytes(int index, byte[] src, int srcIndex, int length);
    900
    901     /**
    902      * Transfers the specified source buffer's data to this buffer starting at
    903      * the specified absolute {@code index} until the source buffer's position
    904      * reaches its limit.
    905      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    906      * this buffer.
    907      *
    908      * @throws IndexOutOfBoundsException
    909      *         if the specified {@code index} is less than {@code 0} or
    910      *         if {@code index + src.remaining()} is greater than
    911      *            {@code this.capacity}
    912      */
    913     void setBytes(int index, ByteBuffer src);
    914
    915     /**
    916      * Transfers the content of the specified source stream to this buffer
    917      * starting at the specified absolute {@code index}.
    918      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    919      * this buffer.
    920      *
    921      * @param length the number of bytes to transfer
    922      *
    923      * @return the actual number of bytes read in from the specified channel.
    924      *         {@code -1} if the specified channel is closed.
    925      *
    926      * @throws IndexOutOfBoundsException
    927      *         if the specified {@code index} is less than {@code 0} or
    928      *         if {@code index + length} is greater than {@code this.capacity}
    929      * @throws IOException
    930      *         if the specified stream threw an exception during I/O
    931      */
    932     int setBytes(int index, InputStream in, int length) throws IOException;
    933
    934     /**
    935      * Transfers the content of the specified source channel to this buffer
    936      * starting at the specified absolute {@code index}.
    937      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    938      * this buffer.
    939      *
    940      * @param length the maximum number of bytes to transfer
    941      *
    942      * @return the actual number of bytes read in from the specified channel.
    943      *         {@code -1} if the specified channel is closed.
    944      *
    945      * @throws IndexOutOfBoundsException
    946      *         if the specified {@code index} is less than {@code 0} or
    947      *         if {@code index + length} is greater than {@code this.capacity}
    948      * @throws IOException
    949      *         if the specified channel threw an exception during I/O
    950      */
    951     int  setBytes(int index, ScatteringByteChannel in, int length) throws IOException;
    952
    953     /**
    954      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the specified
    955      * absolute {@code index}.
    956      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    957      * this buffer.
    958      *
    959      * @param length the number of <tt>NUL</tt>s to write to the buffer
    960      *
    961      * @throws IndexOutOfBoundsException
    962      *         if the specified {@code index} is less than {@code 0} or
    963      *         if {@code index + length} is greater than {@code this.capacity}
    964      */
    965     void setZero(int index, int length);
    966
    967     /**
    968      * Gets a byte at the current {@code readerIndex} and increases
    969      * the {@code readerIndex} by {@code 1} in this buffer.
    970      *
    971      * @throws IndexOutOfBoundsException
    972      *         if {@code this.readableBytes} is less than {@code 1}
    973      */
    974     byte  readByte();
    975
    976     /**
    977      * Gets an unsigned byte at the current {@code readerIndex} and increases
    978      * the {@code readerIndex} by {@code 1} in this buffer.
    979      *
    980      * @throws IndexOutOfBoundsException
    981      *         if {@code this.readableBytes} is less than {@code 1}
    982      */
    983     short readUnsignedByte();
    984
    985     /**
    986      * Gets a 16-bit short integer at the current {@code readerIndex}
    987      * and increases the {@code readerIndex} by {@code 2} in this buffer.
    988      *
    989      * @throws IndexOutOfBoundsException
    990      *         if {@code this.readableBytes} is less than {@code 2}
    991      */
    992     short readShort();
    993
    994     /**
    995      * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
    996      * and increases the {@code readerIndex} by {@code 2} in this buffer.
    997      *
    998      * @throws IndexOutOfBoundsException
    999      *         if {@code this.readableBytes} is less than {@code 2}
    1000      */
    1001     int   readUnsignedShort();
    1002
    1003     /**
    1004      * Gets a 24-bit medium integer at the current {@code readerIndex}
    1005      * and increases the {@code readerIndex} by {@code 3} in this buffer.
    1006      *
    1007      * @throws IndexOutOfBoundsException
    1008      *         if {@code this.readableBytes} is less than {@code 3}
    1009      */
    1010     int   readMedium();
    1011
    1012     /**
    1013      * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
    1014      * and increases the {@code readerIndex} by {@code 3} in this buffer.
    1015      *
    1016      * @throws IndexOutOfBoundsException
    1017      *         if {@code this.readableBytes} is less than {@code 3}
    1018      */
    1019     int   readUnsignedMedium();
    1020
    1021     /**
    1022      * Gets a 32-bit integer at the current {@code readerIndex}
    1023      * and increases the {@code readerIndex} by {@code 4} in this buffer.
    1024      *
    1025      * @throws IndexOutOfBoundsException
    1026      *         if {@code this.readableBytes} is less than {@code 4}
    1027      */
    1028     int   readInt();
    1029
    1030     /**
    1031      * Gets an unsigned 32-bit integer at the current {@code readerIndex}
    1032      * and increases the {@code readerIndex} by {@code 4} in this buffer.
    1033      *
    1034      * @throws IndexOutOfBoundsException
    1035      *         if {@code this.readableBytes} is less than {@code 4}
    1036      */
    1037     long  readUnsignedInt();
    1038
    1039     /**
    1040      * Gets a 64-bit integer at the current {@code readerIndex}
    1041      * and increases the {@code readerIndex} by {@code 8} in this buffer.
    1042      *
    1043      * @throws IndexOutOfBoundsException
    1044      *         if {@code this.readableBytes} is less than {@code 8}
    1045      */
    1046     long  readLong();
    1047
    1048     /**
    1049      * Gets a 2-byte UTF-16 character at the current {@code readerIndex}
    1050      * and increases the {@code readerIndex} by {@code 2} in this buffer.
    1051      *
    1052      * @throws IndexOutOfBoundsException
    1053      *         if {@code this.readableBytes} is less than {@code 2}
    1054      */
    1055     char  readChar();
    1056
    1057     /**
    1058      * Gets a 32-bit floating point number at the current {@code readerIndex}
    1059      * and increases the {@code readerIndex} by {@code 4} in this buffer.
    1060      *
    1061      * @throws IndexOutOfBoundsException
    1062      *         if {@code this.readableBytes} is less than {@code 4}
    1063      */
    1064     float readFloat();
    1065
    1066     /**
    1067      * Gets a 64-bit floating point number at the current {@code readerIndex}
    1068      * and increases the {@code readerIndex} by {@code 8} in this buffer.
    1069      *
    1070      * @throws IndexOutOfBoundsException
    1071      *         if {@code this.readableBytes} is less than {@code 8}
    1072      */
    1073     double readDouble();
    1074
    1075     /**
    1076      * Transfers this buffer's data to a newly created buffer starting at
    1077      * the current {@code readerIndex} and increases the {@code readerIndex}
    1078      * by the number of the transferred bytes (= {@code length}).
    1079      * The returned buffer's {@code readerIndex} and {@code writerIndex} are
    1080      * {@code 0} and {@code length} respectively.
    1081      *
    1082      * @param length the number of bytes to transfer
    1083      *
    1084      * @return the newly created buffer which contains the transferred bytes
    1085      *
    1086      * @throws IndexOutOfBoundsException
    1087      *         if {@code length} is greater than {@code this.readableBytes}
    1088      */
    1089     ChannelBuffer readBytes(int length);
    1090
    1091     /**
    1092      * @deprecated Use {@link #bytesBefore(ChannelBufferIndexFinder)} and {@link #readBytes(int)} instead.
    1093      */
    1094     @Deprecated
    1095     ChannelBuffer readBytes(ChannelBufferIndexFinder indexFinder);
    1096
    1097     /**
    1098      * Returns a new slice of this buffer's sub-region starting at the current
    1099      * {@code readerIndex} and increases the {@code readerIndex} by the size
    1100      * of the new slice (= {@code length}).
    1101      *
    1102      * @param length the size of the new slice
    1103      *
    1104      * @return the newly created slice
    1105      *
    1106      * @throws IndexOutOfBoundsException
    1107      *         if {@code length} is greater than {@code this.readableBytes}
    1108      */
    1109     ChannelBuffer readSlice(int length);
    1110
    1111     /**
    1112      * @deprecated Use {@link #bytesBefore(ChannelBufferIndexFinder)} and {@link #readSlice(int)} instead.
    1113      */
    1114     @Deprecated
    1115     ChannelBuffer readSlice(ChannelBufferIndexFinder indexFinder);
    1116
    1117     /**
    1118      * Transfers this buffer's data to the specified destination starting at
    1119      * the current {@code readerIndex} until the destination becomes
    1120      * non-writable, and increases the {@code readerIndex} by the number of the
    1121      * transferred bytes.  This method is basically same with
    1122      * {@link #readBytes(ChannelBuffer, int, int)}, except that this method
    1123      * increases the {@code writerIndex} of the destination by the number of
    1124      * the transferred bytes while {@link #readBytes(ChannelBuffer, int, int)}
    1125      * does not.
    1126      *
    1127      * @throws IndexOutOfBoundsException
    1128      *         if {@code dst.writableBytes} is greater than
    1129      *            {@code this.readableBytes}
    1130      */
    1131     void readBytes(ChannelBuffer dst);
    1132
    1133     /**
    1134      * Transfers this buffer's data to the specified destination starting at
    1135      * the current {@code readerIndex} and increases the {@code readerIndex}
    1136      * by the number of the transferred bytes (= {@code length}).  This method
    1137      * is basically same with {@link #readBytes(ChannelBuffer, int, int)},
    1138      * except that this method increases the {@code writerIndex} of the
    1139      * destination by the number of the transferred bytes (= {@code length})
    1140      * while {@link #readBytes(ChannelBuffer, int, int)} does not.
    1141      *
    1142      * @throws IndexOutOfBoundsException
    1143      *         if {@code length} is greater than {@code this.readableBytes} or
    1144      *         if {@code length} is greater than {@code dst.writableBytes}
    1145      */
    1146     void readBytes(ChannelBuffer dst, int length);
    1147
    1148     /**
    1149      * Transfers this buffer's data to the specified destination starting at
    1150      * the current {@code readerIndex} and increases the {@code readerIndex}
    1151      * by the number of the transferred bytes (= {@code length}).
    1152      *
    1153      * @param dstIndex the first index of the destination
    1154      * @param length   the number of bytes to transfer
    1155      *
    1156      * @throws IndexOutOfBoundsException
    1157      *         if the specified {@code dstIndex} is less than {@code 0},
    1158      *         if {@code length} is greater than {@code this.readableBytes}, or
    1159      *         if {@code dstIndex + length} is greater than
    1160      *            {@code dst.capacity}
    1161      */
    1162     void readBytes(ChannelBuffer dst, int dstIndex, int length);
    1163
    1164     /**
    1165      * Transfers this buffer's data to the specified destination starting at
    1166      * the current {@code readerIndex} and increases the {@code readerIndex}
    1167      * by the number of the transferred bytes (= {@code dst.length}).
    1168      *
    1169      * @throws IndexOutOfBoundsException
    1170      *         if {@code dst.length} is greater than {@code this.readableBytes}
    1171      */
    1172     void readBytes(byte[] dst);
    1173
    1174     /**
    1175      * Transfers this buffer's data to the specified destination starting at
    1176      * the current {@code readerIndex} and increases the {@code readerIndex}
    1177      * by the number of the transferred bytes (= {@code length}).
    1178      *
    1179      * @param dstIndex the first index of the destination
    1180      * @param length   the number of bytes to transfer
    1181      *
    1182      * @throws IndexOutOfBoundsException
    1183      *         if the specified {@code dstIndex} is less than {@code 0},
    1184      *         if {@code length} is greater than {@code this.readableBytes}, or
    1185      *         if {@code dstIndex + length} is greater than {@code dst.length}
    1186      */
    1187     void readBytes(byte[] dst, int dstIndex, int length);
    1188
    1189     /**
    1190      * Transfers this buffer's data to the specified destination starting at
    1191      * the current {@code readerIndex} until the destination's position
    1192      * reaches its limit, and increases the {@code readerIndex} by the
    1193      * number of the transferred bytes.
    1194      *
    1195      * @throws IndexOutOfBoundsException
    1196      *         if {@code dst.remaining()} is greater than
    1197      *            {@code this.readableBytes}
    1198      */
    1199     void readBytes(ByteBuffer dst);
    1200
    1201     /**
    1202      * Transfers this buffer's data to the specified stream starting at the
    1203      * current {@code readerIndex}.
    1204      *
    1205      * @param length the number of bytes to transfer
    1206      *
    1207      * @throws IndexOutOfBoundsException
    1208      *         if {@code length} is greater than {@code this.readableBytes}
    1209      * @throws IOException
    1210      *         if the specified stream threw an exception during I/O
    1211      */
    1212     void readBytes(OutputStream out, int length) throws IOException;
    1213
    1214     /**
    1215      * Transfers this buffer's data to the specified stream starting at the
    1216      * current {@code readerIndex}.
    1217      *
    1218      * @param length the maximum number of bytes to transfer
    1219      *
    1220      * @return the actual number of bytes written out to the specified channel
    1221      *
    1222      * @throws IndexOutOfBoundsException
    1223      *         if {@code length} is greater than {@code this.readableBytes}
    1224      * @throws IOException
    1225      *         if the specified channel threw an exception during I/O
    1226      */
    1227     int  readBytes(GatheringByteChannel out, int length) throws IOException;
    1228
    1229     /**
    1230      * Increases the current {@code readerIndex} by the specified
    1231      * {@code length} in this buffer.
    1232      *
    1233      * @throws IndexOutOfBoundsException
    1234      *         if {@code length} is greater than {@code this.readableBytes}
    1235      */
    1236     void skipBytes(int length);
    1237
    1238     /**
    1239      * @deprecated Use {@link #bytesBefore(ChannelBufferIndexFinder)} and {@link #skipBytes(int)} instead.
    1240      */
    1241     @Deprecated
    1242     int  skipBytes(ChannelBufferIndexFinder indexFinder);
    1243
    1244     /**
    1245      * Sets the specified byte at the current {@code writerIndex}
    1246      * and increases the {@code writerIndex} by {@code 1} in this buffer.
    1247      * The 24 high-order bits of the specified value are ignored.
    1248      *
    1249      * @throws IndexOutOfBoundsException
    1250      *         if {@code this.writableBytes} is less than {@code 1}
    1251      */
    1252     void writeByte(int   value);
    1253
    1254     /**
    1255      * Sets the specified 16-bit short integer at the current
    1256      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
    1257      * in this buffer.  The 16 high-order bits of the specified value are ignored.
    1258      *
    1259      * @throws IndexOutOfBoundsException
    1260      *         if {@code this.writableBytes} is less than {@code 2}
    1261      */
    1262     void writeShort(int value);
    1263
    1264     /**
    1265      * Sets the specified 24-bit medium integer at the current
    1266      * {@code writerIndex} and increases the {@code writerIndex} by {@code 3}
    1267      * in this buffer.
    1268      *
    1269      * @throws IndexOutOfBoundsException
    1270      *         if {@code this.writableBytes} is less than {@code 3}
    1271      */
    1272     void writeMedium(int   value);
    1273
    1274     /**
    1275      * Sets the specified 32-bit integer at the current {@code writerIndex}
    1276      * and increases the {@code writerIndex} by {@code 4} in this buffer.
    1277      *
    1278      * @throws IndexOutOfBoundsException
    1279      *         if {@code this.writableBytes} is less than {@code 4}
    1280      */
    1281     void writeInt(int   value);
    1282
    1283     /**
    1284      * Sets the specified 64-bit long integer at the current
    1285      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
    1286      * in this buffer.
    1287      *
    1288      * @throws IndexOutOfBoundsException
    1289      *         if {@code this.writableBytes} is less than {@code 8}
    1290      */
    1291     void writeLong(long  value);
    1292
    1293     /**
    1294      * Sets the specified 2-byte UTF-16 character at the current
    1295      * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
    1296      * in this buffer.  The 16 high-order bits of the specified value are ignored.
    1297      *
    1298      * @throws IndexOutOfBoundsException
    1299      *         if {@code this.writableBytes} is less than {@code 2}
    1300      */
    1301     void writeChar(int value);
    1302
    1303     /**
    1304      * Sets the specified 32-bit floating point number at the current
    1305      * {@code writerIndex} and increases the {@code writerIndex} by {@code 4}
    1306      * in this buffer.
    1307      *
    1308      * @throws IndexOutOfBoundsException
    1309      *         if {@code this.writableBytes} is less than {@code 4}
    1310      */
    1311     void writeFloat(float value);
    1312
    1313     /**
    1314      * Sets the specified 64-bit floating point number at the current
    1315      * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
    1316      * in this buffer.
    1317      *
    1318      * @throws IndexOutOfBoundsException
    1319      *         if {@code this.writableBytes} is less than {@code 8}
    1320      */
    1321     void writeDouble(double value);
    1322
    1323     /**
    1324      * Transfers the specified source buffer's data to this buffer starting at
    1325      * the current {@code writerIndex} until the source buffer becomes
    1326      * unreadable, and increases the {@code writerIndex} by the number of
    1327      * the transferred bytes.  This method is basically same with
    1328      * {@link #writeBytes(ChannelBuffer, int, int)}, except that this method
    1329      * increases the {@code readerIndex} of the source buffer by the number of
    1330      * the transferred bytes while {@link #writeBytes(ChannelBuffer, int, int)}
    1331      * does not.
    1332      *
    1333      * @throws IndexOutOfBoundsException
    1334      *         if {@code src.readableBytes} is greater than
    1335      *            {@code this.writableBytes}
    1336      */
    1337     void writeBytes(ChannelBuffer src);
    1338
    1339     /**
    1340      * Transfers the specified source buffer's data to this buffer starting at
    1341      * the current {@code writerIndex} and increases the {@code writerIndex}
    1342      * by the number of the transferred bytes (= {@code length}).  This method
    1343      * is basically same with {@link #writeBytes(ChannelBuffer, int, int)},
    1344      * except that this method increases the {@code readerIndex} of the source
    1345      * buffer by the number of the transferred bytes (= {@code length}) while
    1346      * {@link #writeBytes(ChannelBuffer, int, int)} does not.
    1347      *
    1348      * @param length the number of bytes to transfer
    1349      *
    1350      * @throws IndexOutOfBoundsException
    1351      *         if {@code length} is greater than {@code this.writableBytes} or
    1352      *         if {@code length} is greater then {@code src.readableBytes}
    1353      */
    1354     void writeBytes(ChannelBuffer src, int length);
    1355
    1356     /**
    1357      * Transfers the specified source buffer's data to this buffer starting at
    1358      * the current {@code writerIndex} and increases the {@code writerIndex}
    1359      * by the number of the transferred bytes (= {@code length}).
    1360      *
    1361      * @param srcIndex the first index of the source
    1362      * @param length   the number of bytes to transfer
    1363      *
    1364      * @throws IndexOutOfBoundsException
    1365      *         if the specified {@code srcIndex} is less than {@code 0},
    1366      *         if {@code srcIndex + length} is greater than
    1367      *            {@code src.capacity}, or
    1368      *         if {@code length} is greater than {@code this.writableBytes}
    1369      */
    1370     void writeBytes(ChannelBuffer src, int srcIndex, int length);
    1371
    1372     /**
    1373      * Transfers the specified source array's data to this buffer starting at
    1374      * the current {@code writerIndex} and increases the {@code writerIndex}
    1375      * by the number of the transferred bytes (= {@code src.length}).
    1376      *
    1377      * @throws IndexOutOfBoundsException
    1378      *         if {@code src.length} is greater than {@code this.writableBytes}
    1379      */
    1380     void writeBytes(byte[] src);
    1381
    1382     /**
    1383      * Transfers the specified source array's data to this buffer starting at
    1384      * the current {@code writerIndex} and increases the {@code writerIndex}
    1385      * by the number of the transferred bytes (= {@code length}).
    1386      *
    1387      * @param srcIndex the first index of the source
    1388      * @param length   the number of bytes to transfer
    1389      *
    1390      * @throws IndexOutOfBoundsException
    1391      *         if the specified {@code srcIndex} is less than {@code 0},
    1392      *         if {@code srcIndex + length} is greater than
    1393      *            {@code src.length}, or
    1394      *         if {@code length} is greater than {@code this.writableBytes}
    1395      */
    1396     void writeBytes(byte[] src, int srcIndex, int length);
    1397
    1398     /**
    1399      * Transfers the specified source buffer's data to this buffer starting at
    1400      * the current {@code writerIndex} until the source buffer's position
    1401      * reaches its limit, and increases the {@code writerIndex} by the
    1402      * number of the transferred bytes.
    1403      *
    1404      * @throws IndexOutOfBoundsException
    1405      *         if {@code src.remaining()} is greater than
    1406      *            {@code this.writableBytes}
    1407      */
    1408     void writeBytes(ByteBuffer src);
    1409
    1410     /**
    1411      * Transfers the content of the specified stream to this buffer
    1412      * starting at the current {@code writerIndex} and increases the
    1413      * {@code writerIndex} by the number of the transferred bytes.
    1414      *
    1415      * @param length the number of bytes to transfer
    1416      *
    1417      * @return the actual number of bytes read in from the specified stream
    1418      *
    1419      * @throws IndexOutOfBoundsException
    1420      *         if {@code length} is greater than {@code this.writableBytes}
    1421      * @throws IOException
    1422      *         if the specified stream threw an exception during I/O
    1423      */
    1424     int  writeBytes(InputStream in, int length) throws IOException;
    1425
    1426     /**
    1427      * Transfers the content of the specified channel to this buffer
    1428      * starting at the current {@code writerIndex} and increases the
    1429      * {@code writerIndex} by the number of the transferred bytes.
    1430      *
    1431      * @param length the maximum number of bytes to transfer
    1432      *
    1433      * @return the actual number of bytes read in from the specified channel
    1434      *
    1435      * @throws IndexOutOfBoundsException
    1436      *         if {@code length} is greater than {@code this.writableBytes}
    1437      * @throws IOException
    1438      *         if the specified channel threw an exception during I/O
    1439      */
    1440     int  writeBytes(ScatteringByteChannel in, int length) throws IOException;
    1441
    1442     /**
    1443      * Fills this buffer with <tt>NUL (0x00)</tt> starting at the current
    1444      * {@code writerIndex} and increases the {@code writerIndex} by the
    1445      * specified {@code length}.
    1446      *
    1447      * @param length the number of <tt>NUL</tt>s to write to the buffer
    1448      *
    1449      * @throws IndexOutOfBoundsException
    1450      *         if {@code length} is greater than {@code this.writableBytes}
    1451      */
    1452     void writeZero(int length);
    1453
    1454     /**
    1455      * Locates the first occurrence of the specified {@code value} in this
    1456      * buffer.  The search takes place from the specified {@code fromIndex}
    1457      * (inclusive)  to the specified {@code toIndex} (exclusive).
    1458      * <p>
    1459      * If {@code fromIndex} is greater than {@code toIndex}, the search is
    1460      * performed in a reversed order.
    1461      * <p>
    1462      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1463      * this buffer.
    1464      *
    1465      * @return the absolute index of the first occurrence if found.
    1466      *         {@code -1} otherwise.
    1467      */
    1468     int indexOf(int fromIndex, int toIndex, byte value);
    1469
    1470     /**
    1471      * Locates the first place where the specified {@code indexFinder}
    1472      * returns {@code true}.  The search takes place from the specified
    1473      * {@code fromIndex} (inclusive) to the specified {@code toIndex}
    1474      * (exclusive).
    1475      * <p>
    1476      * If {@code fromIndex} is greater than {@code toIndex}, the search is
    1477      * performed in a reversed order.
    1478      * <p>
    1479      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1480      * this buffer.
    1481      *
    1482      * @return the absolute index where the specified {@code indexFinder}
    1483      *         returned {@code true}.  {@code -1} if the {@code indexFinder}
    1484      *         did not return {@code true} at all.
    1485      */
    1486     int indexOf(int fromIndex, int toIndex, ChannelBufferIndexFinder indexFinder);
    1487
    1488     /**
    1489      * Locates the first occurrence of the specified {@code value} in this
    1490      * buffer.  The search takes place from the current {@code readerIndex}
    1491      * (inclusive) to the current {@code writerIndex} (exclusive).
    1492      * <p>
    1493      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1494      * this buffer.
    1495      *
    1496      * @return the number of bytes between the current {@code readerIndex}
    1497      *         and the first occurrence if found. {@code -1} otherwise.
    1498      */
    1499     int bytesBefore(byte value);
    1500
    1501     /**
    1502      * Locates the first place where the specified {@code indexFinder} returns
    1503      * {@code true}.  The search takes place from the current {@code readerIndex}
    1504      * (inclusive) to the current {@code writerIndex}.
    1505      * <p>
    1506      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1507      * this buffer.
    1508      *
    1509      * @return the number of bytes between the current {@code readerIndex}
    1510      *         and the first place where the {@code indexFinder} returned
    1511      *         {@code true}.  {@code -1} if the {@code indexFinder} did not
    1512      *         return {@code true} at all.
    1513      */
    1514     int bytesBefore(ChannelBufferIndexFinder indexFinder);
    1515
    1516     /**
    1517      * Locates the first occurrence of the specified {@code value} in this
    1518      * buffer.  The search starts from the current {@code readerIndex}
    1519      * (inclusive) and lasts for the specified {@code length}.
    1520      * <p>
    1521      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1522      * this buffer.
    1523      *
    1524      * @return the number of bytes between the current {@code readerIndex}
    1525      *         and the first occurrence if found. {@code -1} otherwise.
    1526      *
    1527      * @throws IndexOutOfBoundsException
    1528      *         if {@code length} is greater than {@code this.readableBytes}
    1529      */
    1530     int bytesBefore(int length, byte value);
    1531
    1532     /**
    1533      * Locates the first place where the specified {@code indexFinder} returns
    1534      * {@code true}.  The search starts the current {@code readerIndex}
    1535      * (inclusive) and lasts for the specified {@code length}.
    1536      * <p>
    1537      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1538      * this buffer.
    1539      *
    1540      * @return the number of bytes between the current {@code readerIndex}
    1541      *         and the first place where the {@code indexFinder} returned
    1542      *         {@code true}.  {@code -1} if the {@code indexFinder} did not
    1543      *         return {@code true} at all.
    1544      *
    1545      * @throws IndexOutOfBoundsException
    1546      *         if {@code length} is greater than {@code this.readableBytes}
    1547      */
    1548     int bytesBefore(int length, ChannelBufferIndexFinder indexFinder);
    1549
    1550     /**
    1551      * Locates the first occurrence of the specified {@code value} in this
    1552      * buffer.  The search starts from the specified {@code index} (inclusive)
    1553      * and lasts for the specified {@code length}.
    1554      * <p>
    1555      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1556      * this buffer.
    1557      *
    1558      * @return the number of bytes between the specified {@code index}
    1559      *         and the first occurrence if found. {@code -1} otherwise.
    1560      *
    1561      * @throws IndexOutOfBoundsException
    1562      *         if {@code index + length} is greater than {@code this.capacity}
    1563      */
    1564     int bytesBefore(int index, int length, byte value);
    1565
    1566     /**
    1567      * Locates the first place where the specified {@code indexFinder} returns
    1568      * {@code true}.  The search starts the specified {@code index} (inclusive)
    1569      * and lasts for the specified {@code length}.
    1570      * <p>
    1571      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1572      * this buffer.
    1573      *
    1574      * @return the number of bytes between the specified {@code index}
    1575      *         and the first place where the {@code indexFinder} returned
    1576      *         {@code true}.  {@code -1} if the {@code indexFinder} did not
    1577      *         return {@code true} at all.
    1578      *
    1579      * @throws IndexOutOfBoundsException
    1580      *         if {@code index + length} is greater than {@code this.capacity}
    1581      */
    1582     int bytesBefore(int index, int length, ChannelBufferIndexFinder indexFinder);
    1583
    1584     /**
    1585      * Returns a copy of this buffer's readable bytes.  Modifying the content
    1586      * of the returned buffer or this buffer does not affect each other at all.
    1587      * This method is identical to {@code buf.copy(buf.readerIndex(), buf.readableBytes())}.
    1588      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1589      * this buffer.
    1590      */
    1591     ChannelBuffer copy();
    1592
    1593     /**
    1594      * Returns a copy of this buffer's sub-region.  Modifying the content of
    1595      * the returned buffer or this buffer does not affect each other at all.
    1596      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1597      * this buffer.
    1598      */
    1599     ChannelBuffer copy(int index, int length);
    1600
    1601     /**
    1602      * Returns a slice of this buffer's readable bytes. Modifying the content
    1603      * of the returned buffer or this buffer affects each other's content
    1604      * while they maintain separate indexes and marks.  This method is
    1605      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
    1606      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1607      * this buffer.
    1608      */
    1609     ChannelBuffer slice();
    1610
    1611     /**
    1612      * Returns a slice of this buffer's sub-region. Modifying the content of
    1613      * the returned buffer or this buffer affects each other's content while
    1614      * they maintain separate indexes and marks.
    1615      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1616      * this buffer.
    1617      */
    1618     ChannelBuffer slice(int index, int length);
    1619
    1620     /**
    1621      * Returns a buffer which shares the whole region of this buffer.
    1622      * Modifying the content of the returned buffer or this buffer affects
    1623      * each other's content while they maintain separate indexes and marks.
    1624      * This method is identical to {@code buf.slice(0, buf.capacity())}.
    1625      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1626      * this buffer.
    1627      */
    1628     ChannelBuffer duplicate();
    1629
    1630     /**
    1631      * Converts this buffer's readable bytes into a NIO buffer.  The returned
    1632      * buffer might or might not share the content with this buffer, while
    1633      * they have separate indexes and marks.  This method is identical to
    1634      * {@code buf.toByteBuffer(buf.readerIndex(), buf.readableBytes())}.
    1635      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1636      * this buffer.
    1637      */
    1638     ByteBuffer toByteBuffer();
    1639
    1640     /**
    1641      * Converts this buffer's sub-region into a NIO buffer.  The returned
    1642      * buffer might or might not share the content with this buffer, while
    1643      * they have separate indexes and marks.
    1644      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1645      * this buffer.
    1646      */
    1647     ByteBuffer toByteBuffer(int index, int length);
    1648
    1649     /**
    1650      * Converts this buffer's readable bytes into an array of NIO buffers.
    1651      * The returned buffers might or might not share the content with this
    1652      * buffer, while they have separate indexes and marks.  This method is
    1653      * identical to {@code buf.toByteBuffers(buf.readerIndex(), buf.readableBytes())}.
    1654      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1655      * this buffer.
    1656      */
    1657     ByteBuffer[] toByteBuffers();
    1658
    1659     /**
    1660      * Converts this buffer's sub-region into an array of NIO buffers.
    1661      * The returned buffers might or might not share the content with this
    1662      * buffer, while they have separate indexes and marks.
    1663      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1664      * this buffer.
    1665      */
    1666     ByteBuffer[] toByteBuffers(int index, int length);
    1667
    1668     /**
    1669      * Returns {@code true} if and only if this buffer has a backing byte array.
    1670      * If this method returns true, you can safely call {@link #array()} and
    1671      * {@link #arrayOffset()}.
    1672      */
    1673     boolean hasArray();
    1674
    1675     /**
    1676      * Returns the backing byte array of this buffer.
    1677      *
    1678      * @throws UnsupportedOperationException
    1679      *         if there no accessible backing byte array
    1680      */
    1681     byte[] array();
    1682
    1683     /**
    1684      * Returns the offset of the first byte within the backing byte array of
    1685      * this buffer.
    1686      *
    1687      * @throws UnsupportedOperationException
    1688      *         if there no accessible backing byte array
    1689      */
    1690     int arrayOffset();
    1691
    1692     /**
    1693      * Decodes this buffer's readable bytes into a string with the specified
    1694      * character set name.  This method is identical to
    1695      * {@code buf.toString(buf.readerIndex(), buf.readableBytes(), charsetName)}.
    1696      * This method does not modify {@code readerIndex} or {@code writerIndex} of
    1697      * this buffer.
    1698      *
    1699      * @throws UnsupportedCharsetException
    1700      *         if the specified character set name is not supported by the
    1701      *         current VM
    1702      */
    1703     String toString(Charset charset);
    1704
    1705     /**
    1706      * Decodes this buffer's sub-region into a string with the specified
    1707      * character set.  This method does not modify {@code readerIndex} or
    1708      * {@code writerIndex} of this buffer.
    1709      */
    1710     String toString(int index, int length, Charset charset);
    1711
    1712     /**
    1713      * @deprecated Use {@link #toString(Charset)} instead.
    1714      */
    1715     @Deprecated
    1716     String toString(String charsetName);
    1717
    1718     /**
    1719      * @deprecated Use {@link #bytesBefore(ChannelBufferIndexFinder)} and {@link #toString(int, int, Charset)} instead.
    1720      */
    1721     @Deprecated
    1722     String toString(
    1723             String charsetName, ChannelBufferIndexFinder terminatorFinder);
    1724
    1725     /**
    1726      * @deprecated Use {@link #bytesBefore(int, int, ChannelBufferIndexFinder)} and
    1727      * {@link #toString(int, int, Charset)} instead.
    1728      */
    1729     @Deprecated
    1730     String toString(int index, int length, String charsetName);
    1731
    1732     /**
    1733      * @deprecated Use {@link #bytesBefore(int, int, ChannelBufferIndexFinder)} and
    1734      * {@link #toString(int, int, Charset)} instead.
    1735      */
    1736     @Deprecated
    1737     String toString(
    1738             int index, int length, String charsetName,
    1739             ChannelBufferIndexFinder terminatorFinder);
    1740
    1741     /**
    1742      * Returns a hash code which was calculated from the content of this
    1743      * buffer.  If there's a byte array which is
    1744      * {@linkplain #equals(Object) equal to} this array, both arrays should
    1745      * return the same value.
    1746      */
    1747     int hashCode();
    1748
    1749     /**
    1750      * Determines if the content of the specified buffer is identical to the
    1751      * content of this array.  'Identical' here means:
    1752      * <ul>
    1753      * <li>the size of the contents of the two buffers are same and</li>
    1754      * <li>every single byte of the content of the two buffers are same.</li>
    1755      * </ul>
    1756      * Please note that it does not compare {@link #readerIndex()} nor
    1757      * {@link #writerIndex()}.  This method also returns {@code false} for
    1758      * {@code null} and an object which is not an instance of
    1759      * {@link ChannelBuffer} type.
    1760      */
    1761     boolean equals(Object obj);
    1762
    1763     /**
    1764      * Compares the content of the specified buffer to the content of this
    1765      * buffer.  Comparison is performed in the same manner with the string
    1766      * comparison functions of various languages such as {@code strcmp},
    1767      * {@code memcmp} and {@link String#compareTo(String)}.
    1768      */
    1769     int compareTo(ChannelBuffer buffer);
    1770
    1771     /**
    1772      * Returns the string representation of this buffer.  This method does not
    1773      * necessarily return the whole content of the buffer but returns
    1774      * the values of the key properties such as {@link #readerIndex()},
    1775      * {@link #writerIndex()} and {@link #capacity()}.
    1776      */
    1777     String toString();
    1778 }