/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.qpid.protonj2.buffer;

import java.nio.ByteBuffer;
import java.nio.charset.Charset;

/**
 * Buffer type abstraction used to provide users of the proton library with
 * a means of using their own type of byte buffer types in combination with the
 * library tooling.
 */
public interface ProtonBuffer extends Comparable<ProtonBuffer> {

    /**
     * Return the underlying buffer object that backs this {@link ProtonBuffer} instance, or null
     * if there is no backing object.
     *
     * This method should be overridden in buffer abstraction when access to the underlying backing
     * store is needed such as when wrapping pooled resources that need explicit release calls.
     *
     * @return an underlying buffer object or other backing store for this buffer.
     */
    default Object unwrap() { return null; }

    /**
     * @return true if this buffer has a backing byte array that can be accessed.
     */
    boolean hasArray();

    /**
     * Returns the backing array for this ProtonBuffer instance if there is such an array or
     * throws an exception if this ProtonBuffer implementation has no backing array.
     * <p>
     * Changes to the returned array are visible to other users of this ProtonBuffer.
     *
     * @return the backing byte array for this ProtonBuffer.
     *
     * @throws UnsupportedOperationException if this buffer type has no backing array.
     */
    byte[] getArray();

    /**
     * @return the offset of the first byte in the backing array belonging to this buffer.
     *
     * @throws UnsupportedOperationException if this buffer type has no backing array.
     */
    int getArrayOffset();

    /**
     * @return the number of bytes this buffer can currently contain.
     */
    int capacity();

    /**
     * Adjusts the capacity of this buffer.  If the new capacity is less than the current
     * capacity, the content of this buffer is truncated.  If the new capacity is greater
     * than the current capacity, the buffer is appended with unspecified data whose length is
     * new capacity - current capacity.
     *
     * @param newCapacity
     *      the new maximum capacity value of this buffer.
     *
     * @return this buffer for using in call chaining.
     */
    ProtonBuffer capacity(int newCapacity);

    /**
     * Returns the number of bytes that this buffer is allowed to grow to when write
     * operations exceed the current capacity value.
     *
     * @return the number of bytes this buffer is allowed to grow to.
     */
    int maxCapacity();

    /**
     * Ensures that the requested number of bytes is available for write operations
     * in the current buffer, growing the buffer if needed to meet the requested
     * writable capacity.
     *
     * @param amount
     *      The number of bytes beyond the current write index needed.
     *
     * @return this buffer for using in call chaining.
     *
     * @throws IllegalArgumentException if the amount given is less than zero.
     * @throws IndexOutOfBoundsException if the amount given would result in the buffer
     *         exceeding the maximum capacity for this buffer.
     */
    ProtonBuffer ensureWritable(int amount) throws IndexOutOfBoundsException, IllegalArgumentException;

    /**
     * Create a duplicate of this ProtonBuffer instance that shares the same backing
     * data store and but maintains separate position index values.  Changes to one buffer
     * are visible in any of its duplicates.  This method does not copy the read or write
     * markers to the new buffer instance.
     *
     * @return a new ProtonBuffer instance that shares the backing data as this one.
     */
    ProtonBuffer duplicate();

    /**
     * Create a new ProtonBuffer whose contents are a subsequence of the contents of this
     * {@link ProtonBuffer}.
     * <p>
     * The starting point of the new buffer starts at this buffer's current position, the
     * marks and limits of the new buffer will be independent of this buffer however changes
     * to the data backing the buffer will be visible in this buffer.
     *
     * @return a new {@link ProtonBuffer} whose contents are a subsequence of this buffer.
     */
    ProtonBuffer slice();

    /**
     * Create a new ProtonBuffer whose contents are a subsequence of the contents of this
     * {@link ProtonBuffer}.
     * <p>
     * The starting point of the new buffer starts at given index into this buffer and spans
     * the number of bytes given by the length.  Changes to the contents of this buffer or to
     * the produced slice buffer are visible in the other.
     *
     * @param index
     *      The index in this buffer where the slice should begin.
     * @param length
     *      The number of bytes to make visible to the new buffer from this one.
     *
     * @return a new {@link ProtonBuffer} whose contents are a subsequence of this buffer.
     */
    ProtonBuffer slice(int index, int length);

    /**
     * Create a deep copy of the readable bytes of this ProtonBuffer, the returned buffer can
     * be modified without affecting the contents or position markers of this instance.
     *
     * @return a deep copy of this ProtonBuffer instance.
     */
    ProtonBuffer copy();

    /**
     * Returns a copy of this buffer's sub-region.  Modifying the content of
     * the returned buffer or this buffer does not affect each other at all.
     * This method does not modify the value returned from {@link #getReadIndex()}
     * or {@link #getWriteIndex()} of this buffer.
     *
     * @param index
     *      The index in this buffer where the copy should begin
     * @param length
     *      The number of bytes to copy to the new buffer from this one.
     *
     * @return a new ProtonBuffer instance containing the copied bytes.
     */
    ProtonBuffer copy(int index, int length);

    /**
     * Reset the position markers of this buffer, this method is not required to reset
     * the data previously written to this buffer.
     *
     * @return this buffer for using in call chaining.
     */
    ProtonBuffer clear();

    /**
     * Returns a ByteBuffer that represents the readable bytes contained in this buffer.
     * <p>
     * This method should attempt to return a ByteBuffer that shares the backing data store
     * with this buffer however if that is not possible it is permitted that the returned
     * ByteBuffer contain a copy of the readable bytes of this ProtonBuffer.
     *
     * @return a ByteBuffer that represents the readable bytes of this buffer.
     */
    ByteBuffer toByteBuffer();

    /**
     * Returns a ByteBuffer that represents the given span of bytes from the readable portion
     * of this buffer.
     * <p>
     * This method should attempt to return a ByteBuffer that shares the backing data store
     * with this buffer however if that is not possible it is permitted that the returned
     * ByteBuffer contain a copy of the readable bytes of this ProtonBuffer.
     *
     * @param index
     *      The starting index in this where the ByteBuffer view should begin.
     * @param length
     *      The number of bytes to include in the ByteBuffer view.
     *
     * @return a ByteBuffer that represents the given view of this buffers readable bytes.
     */
    ByteBuffer toByteBuffer(int index, int length);

    /**
     * Returns a String created from the buffer's underlying bytes using the specified
     * {@link java.nio.charset.Charset} for the newly created String.
     *
     * @param charset
     *      the {@link java.nio.charset.Charset} to use to construct the new string.
     *
     * @return a string created from the buffer's underlying bytes using the given {@link java.nio.charset.Charset}.
     */
    String toString(Charset charset);

    /**
     * @return the number of bytes available for reading from this buffer.
     */
    int getReadableBytes();

    /**
     * @return the number of bytes that can be written to this buffer before the limit is hit.
     */
    int getWritableBytes();

    /**
     * Gets the current maximum number of bytes that can be written to this buffer.  This is
     * the same value that can be computed by subtracting the current write index from the
     * maximum buffer capacity.
     *
     * @return the maximum number of bytes that can be written to this buffer before the limit is hit.
     */
    int getMaxWritableBytes();

    /**
     * @return the current value of the read index for this buffer.
     */
    int getReadIndex();

    /**
     * Sets the read index for this buffer.
     *
     * @param value The index into the buffer where the read index should be positioned.
     *
     * @return this buffer for use in chaining.
     *
     * @throws IndexOutOfBoundsException if the value given is greater than the write index or negative.
     */
    ProtonBuffer setReadIndex(int value);

    /**
     * @return the current value of the write index for this buffer.
     */
    int getWriteIndex();

    /**
     * Sets the write index for this buffer.
     *
     * @param value The index into the buffer where the write index should be positioned.
     *
     * @return this buffer for use in chaining.
     *
     * @throws IndexOutOfBoundsException if the value less than the read index or greater than the capacity.
     */
    ProtonBuffer setWriteIndex(int value);

    /**
     * Used to set the read index and the write index in one call.  This methods allows for an update
     * to the read index and write index to values that could not be set using simple setReadIndex and
     * setWriteIndex call where the values would violate the constraints placed on them by the value
     * of the other index.
     *
     * @param readIndex
     *      The new read index to assign to this buffer.
     * @param writeIndex
     *      The new write index to assign to this buffer.
     *
     * @return this buffer for use in chaining.
     *
     * @throws IndexOutOfBoundsException if the values violate the basic tenants of readIndex and writeIndex
     */
    ProtonBuffer setIndex(int readIndex, int writeIndex);

    /**
     * Marks the current read index so that it can later be restored by a call to
     * {@link ProtonBuffer#resetReadIndex}, the initial mark value is 0.
     *
     * @return this buffer for use in chaining.
     */
    ProtonBuffer markReadIndex();

    /**
     * Resets the current read index to the previously marked value.
     *
     * @return this buffer for use in chaining.
     *
     * @throws IndexOutOfBoundsException if the current write index is less than the marked read index.
     */
    ProtonBuffer resetReadIndex();

    /**
     * Marks the current write index so that it can later be restored by a call to
     * {@link ProtonBuffer#resetWriteIndex}, the initial mark value is 0.
     *
     * @return this buffer for use in chaining.
     */
    ProtonBuffer markWriteIndex();

    /**
     * Resets the current write index to the previously marked value.
     *
     * @return this buffer for use in chaining.
     *
     * @throws IndexOutOfBoundsException if the current read index is greater than the marked write index.
     */
    ProtonBuffer resetWriteIndex();

    /**
     * @return true if the read index is less than the write index.
     */
    boolean isReadable();

    /**
     * Check if the given number of bytes can be read from the buffer.
     *
     * @param size
     *      the size that is desired in readable bytes
     *
     * @return true if the buffer has at least the given number of readable bytes remaining.
     */
    boolean isReadable(int size);

    /**
     * Compares the remaining content of the current buffer with the remaining content of the
     * given buffer, which must not be null. Each byte is compared in turn as an unsigned value,
     * returning upon the first difference. If no difference is found before the end of one
     * buffer, the shorter buffer is considered less than the other, or else if the same length
     * then they are considered equal.
     *
     * @return  a negative, zero, or positive integer when this buffer is less than, equal to,
     *          or greater than the given buffer.
     * @see Comparable#compareTo(Object)
     */
    @Override int compareTo(ProtonBuffer buffer);

    /**
     * Gets a boolean from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    boolean getBoolean(int index);

    /**
     * Gets a byte from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    byte getByte(int index);

    /**
     * Gets a unsigned byte from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    short getUnsignedByte(int index);

    /**
     * Gets a 2-byte char from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    char getChar(int index);

    /**
     * Gets a short from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    short getShort(int index);

    /**
     * Gets a unsigned short from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    int getUnsignedShort(int index);

    /**
     * Gets a int from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    int getInt(int index);

    /**
     * Gets a unsigned int from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    long getUnsignedInt(int index);

    /**
     * Gets a long from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    long getLong(int index);

    /**
     * Gets a float from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    float getFloat(int index);

    /**
     * Gets a double from the specified index, this method will not modify the read or write
     * index.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     *
     * @return the value read from the given index.
     *
     * @throws IndexOutOfBoundsException if the index is negative or past the current buffer capacity.
     */
    double getDouble(int index);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the specified absolute {@code index} until the destination becomes
     * non-writable.  This method is basically same with
     * {@link #getBytes(int, ProtonBuffer, int, int)}, except that this
     * method increases the {@code writeIndex} of the destination by the
     * number of the transferred bytes while
     * {@link #getBytes(int, ProtonBuffer, int, int)} does not.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * the source buffer (i.e. {@code this}).
     *
     * @param index
     *      The index into the buffer where the value should be read.
     * @param destination
     *      the destination buffer for the bytes to be read
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0} or
     *         if {@code index + dst.writableBytes} is greater than
     *            {@code this.capacity}
     */
    ProtonBuffer getBytes(int index, ProtonBuffer destination);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the specified absolute {@code index}.  This method is basically same
     * with {@link #getBytes(int, ProtonBuffer, int, int)}, except that this
     * method increases the {@code writeIndex} of the destination by the
     * number of the transferred bytes while
     * {@link #getBytes(int, ProtonBuffer, int, int)} does not.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * the source buffer (i.e. {@code this}).
     *
     * @param index
     *      the index in the buffer to start the read from
     * @param destination
     *      the destination buffer for the bytes to be read
     * @param length
     *      the number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0},
     *         if {@code index + length} is greater than
     *            {@code this.capacity}, or
     *         if {@code length} is greater than {@code dst.writableBytes}
     */
    ProtonBuffer getBytes(int index, ProtonBuffer destination, int length);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the specified absolute {@code index}.
     * This method does not modify {@code readIndex} or {@code writeIndex}
     * of both the source (i.e. {@code this}) and the destination.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     * @param destination
     *      The buffer where the bytes read will be written to
     * @param destinationIndex
     *      The index into the destination where the write starts
     * @param length
     *      The number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0},
     *         if the specified {@code dstIndex} is less than {@code 0},
     *         if {@code index + length} is greater than
     *            {@code this.capacity}, or
     *         if {@code dstIndex + length} is greater than
     *            {@code dst.capacity}
     */
    ProtonBuffer getBytes(int index, ProtonBuffer destination, int destinationIndex, int length);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the specified absolute {@code index}.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * this buffer
     *
     * @param index
     *      The index into the buffer where the value should be read.
     * @param destination
     *      The buffer where the bytes read will be written to
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0} or
     *         if {@code index + dst.length} is greater than
     *            {@code this.capacity}
     */
    ProtonBuffer getBytes(int index, byte[] destination);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the specified absolute {@code index}.
     * This method does not modify {@code #getReadIndex()} or {@code #getWriteIndex()}
     * of this buffer.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     * @param destination
     *      The buffer where the bytes read will be written to
     * @param offset
     *      the offset into the destination to begin writing the bytes.
     * @param length
     *      the number of bytes to transfer from this buffer to the target buffer.
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0},
     *         if the specified {@code offset} is less than {@code 0},
     *         if {@code index + length} is greater than
     *            {@code this.capacity}, or
     *         if {@code offset + length} is greater than
     *            {@code target.length}
     */
    ProtonBuffer getBytes(int index, byte[] destination, int offset, int length);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the specified absolute {@code index} until the destination's position
     * reaches its limit.
     * This method does not modify {@code #getReadIndex()} or {@code #getWriteIndex()} of
     * this buffer while the destination's {@code position} will be increased.
     *
     * @param index
     *      The index into the buffer where the value should be read.
     * @param destination
     *      The buffer where the bytes read will be written to
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0} or
     *         if {@code index + destination.remaining()} is greater than
     *            {@code #capacity()}
     */
    ProtonBuffer getBytes(int index, ByteBuffer destination);

    /**
     * Sets the byte value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setByte(int index, int value);

    /**
     * Sets the boolean value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setBoolean(int index, boolean value);

    /**
     * Sets the char value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setChar(int index, int value);

    /**
     * Sets the short value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setShort(int index, int value);

    /**
     * Sets the int value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setInt(int index, int value);

    /**
     * Sets the long value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setLong(int index, long value);

    /**
     * Sets the float value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setFloat(int index, float value);

    /**
     * Sets the double value at the given write index in this buffer's backing data store.
     *
     * @param index
     *      The index to start the write from.
     * @param value
     *      The value to write at the given index.
     *
     * @return a reference to this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the index is negative or the write would exceed capcity.
     */
    ProtonBuffer setDouble(int index, double value);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the specified absolute {@code index} until the source buffer becomes
     * unreadable.  This method is basically same with
     * {@link #setBytes(int, ProtonBuffer, int, int)}, except that this
     * method increases the {@code readIndex} of the source buffer by
     * the number of the transferred bytes while
     * {@link #setBytes(int, ProtonBuffer, int, int)} does not.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * the source buffer (i.e. {@code this}).
     *
     * @param index
     *      The index in this buffer where the write operation starts.
     * @param source
     *      The source buffer from which the bytes are read.
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0} or
     *         if {@code index + source.readableBytes} is greater than
     *            {@code this.capacity}
     */
    ProtonBuffer setBytes(int index, ProtonBuffer source);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the specified absolute {@code index}.  This method is basically same
     * with {@link #setBytes(int, ProtonBuffer, int, int)}, except that this
     * method increases the {@code readIndex} of the source buffer by
     * the number of the transferred bytes while
     * {@link #setBytes(int, ProtonBuffer, int, int)} does not.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * the source buffer (i.e. {@code this}).
     *
     * @param index
     *      The index in this buffer where the write operation starts.
     * @param source
     *      The source buffer from which the bytes are read.
     * @param length
     *      The number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0},
     *         if {@code index + length} is greater than
     *            {@code this.capacity}, or
     *         if {@code length} is greater than {@code source.readableBytes}
     */
    ProtonBuffer setBytes(int index, ProtonBuffer source, int length);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the specified absolute {@code index}.
     * This method does not modify {@code readIndex} or {@code writeIndex}
     * of both the source (i.e. {@code this}) and the destination.
     *
     * @param index
     *      The index in this buffer where the write operation starts.
     * @param source
     *      The source buffer from which the bytes are read.
     * @param sourceIndex
     *      The first index of the source
     * @param length
     *      The number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0},
     *         if the specified {@code sourceIndex} is less than {@code 0},
     *         if {@code index + length} is greater than
     *            {@code this.capacity}, or
     *         if {@code sourceIndex + length} is greater than
     *            {@code source.capacity}
     */
    ProtonBuffer setBytes(int index, ProtonBuffer source, int sourceIndex, int length);

    /**
     * Transfers the specified source array's data to this buffer starting at
     * the specified absolute {@code index}.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * this buffer.
     *
     * @param index
     *      The index in this buffer where the write operation starts.
     * @param source
     *      The source buffer from which the bytes are read.
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0} or
     *         if {@code index + source.length} is greater than
     *            {@code this.capacity}
     */
    ProtonBuffer setBytes(int index, byte[] source);

    /**
     * Transfers the specified source array's data to this buffer starting at
     * the specified absolute {@code index}.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * this buffer.
     *
     * @param index
     *      The index in this buffer where the write operation starts.
     * @param source
     *      The source buffer from which the bytes are read.
     * @param sourceIndex
     *      The first index of the source
     * @param length
     *      The number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0},
     *         if the specified {@code srcIndex} is less than {@code 0},
     *         if {@code index + length} is greater than
     *            {@code this.capacity}, or
     *         if {@code srcIndex + length} is greater than {@code src.length}
     */
    ProtonBuffer setBytes(int index, byte[] source, int sourceIndex, int length);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the specified absolute {@code index} until the source buffer's position
     * reaches its limit.
     * This method does not modify {@code readIndex} or {@code writeIndex} of
     * this buffer.
     *
     * @param index
     *      The index in this buffer where the write operation starts.
     * @param source
     *      The source buffer from which the bytes are read.
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code index} is less than {@code 0} or
     *         if {@code index + src.remaining()} is greater than
     *            {@code this.capacity}
     */
    ProtonBuffer setBytes(int index, ByteBuffer source);

    /**
     * Increases the current {@code readIndex} of this buffer by the specified {@code length}.
     *
     * @param length
     *      the number of bytes in this buffer to skip.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException
     *         if {@code length} is greater than {@code this.readableBytes}
     */
    ProtonBuffer skipBytes(int length);

    /**
     * Reads one byte from the buffer and advances the read index by one.
     *
     * @return a single byte from the ProtonBuffer.
     *
     * @throws IndexOutOfBoundsException if there is no readable bytes left in the buffer.
     */
    byte readByte();

    /**
     * Reads bytes from this buffer and writes them into the destination byte array incrementing
     * the read index by the value of the length of the destination array.
     *
     * @param target
     *      The byte array to write into.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the target array is larger than the readable bytes.
     */
    ProtonBuffer readBytes(byte[] target);

    /**
     * Reads bytes from this buffer and writes them into the destination byte array incrementing
     * the read index by the length value passed.
     *
     * @param target
     *      The byte array to write into.
     * @param length
     *      The number of bytes to read into the given array.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the length is larger than the readable bytes, or length is
     *         greater than the length of the target array, or length is negative.
     */
    ProtonBuffer readBytes(byte[] target, int length);

    /**
     * Reads bytes from this buffer and writes them into the destination byte array incrementing
     * the read index by the length value passed, the bytes are read into the given buffer starting
     * from the given offset value.
     *
     * @param target
     *      The byte array to write into.
     * @param offset
     *      The offset into the given array where bytes are written.
     * @param length
     *      The number of bytes to read into the given array.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the offset is negative, or if the length is greater than
     *         the current readable bytes or if the offset + length is great than the size of the target.
     */
    ProtonBuffer readBytes(byte[] target, int offset, int length);

    /**
     * Reads bytes from this buffer and writes them into the destination ProtonBuffer incrementing
     * the read index by the value of the number of bytes written to the target.  The number of bytes
     * written will be the equal to the writable bytes of the target buffer.  The write index of the
     * target buffer must be incremented number of bytes written into it.
     *
     * @param target
     *      The ProtonBuffer to write into.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IllegalArgumentException if the target buffer is this buffer.
     * @throws IndexOutOfBoundsException if the target buffer has more writable bytes than this buffer
     *         has readable bytes.
     */
    ProtonBuffer readBytes(ProtonBuffer target);

    /**
     * Reads bytes from this buffer and writes them into the destination ProtonBuffer incrementing
     * the read index by the number of bytes written.  The write index of the target buffer must be
     * incremented number of bytes written into it.
     *
     * @param target
     *      The ProtonBuffer to write into.
     * @param length
     *      The number of bytes to read into the given buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the length value is greater than the readable bytes of
     *         this buffer or is greater than the writable bytes of the target buffer..
     */
    ProtonBuffer readBytes(ProtonBuffer target, int length);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the current {@code readIndex} and increases the {@code readIndex}
     * by the number of the transferred bytes (= {@code length}).
     *
     * @param target
     *      The ProtonBuffer to write into.
     * @param offset
     *      The offset into the given buffer where bytes are written.
     * @param length
     *      The number of bytes to read into the given buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the offset is negative, or if the length is greater than
     *         the current readable bytes or if the offset + length is great than the size of the target.
     */
    ProtonBuffer readBytes(ProtonBuffer target, int offset, int length);

    /**
     * Transfers this buffer's data to the specified destination starting at
     * the current {@code readIndex} until the destination's position
     * reaches its limit, and increases the {@code readIndex} by the
     * number of the transferred bytes.
     *
     * @param destination
     *      The target ByteBuffer to write into.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if the destination does not have enough capacity.
     */
    ProtonBuffer readBytes(ByteBuffer destination);

    /**
     * Reads a boolean value from the buffer and advances the read index by one.
     *
     * @return boolean value read from the buffer.
     *
     * @throws IndexOutOfBoundsException if a value cannot be read from the buffer.
     */
    boolean readBoolean();

    /**
     * Reads a short value from the buffer and advances the read index by two.
     *
     * @return short value read from the buffer.
     *
     * @throws IndexOutOfBoundsException if a value cannot be read from the buffer.
     */
    short readShort();

    /**
     * Reads a integer value from the buffer and advances the read index by four.
     *
     * @return integer value read from the buffer.
     *
     * @throws IndexOutOfBoundsException if a value cannot be read from the buffer.
     */
    int readInt();

    /**
     * Reads a long value from the buffer and advances the read index by eight.
     *
     * @return long value read from the buffer.
     *
     * @throws IndexOutOfBoundsException if a value cannot be read from the buffer.
     */
    long readLong();

    /**
     * Reads a float value from the buffer and advances the read index by four.
     *
     * @return float value read from the buffer.
     *
     * @throws IndexOutOfBoundsException if a value cannot be read from the buffer.
     */
    float readFloat();

    /**
     * Reads a double value from the buffer and advances the read index by eight.
     *
     * @return double value read from the buffer.
     *
     * @throws IndexOutOfBoundsException if a value cannot be read from the buffer.
     */
    double readDouble();

    /**
     * @return true if the buffer has bytes remaining between the write index and the capacity.
     */
    boolean isWritable();

    /**
     * Check if the requested number of bytes can be written into this buffer.
     *
     * @param size
     *      The number of bytes that is being checked for writability.
     *
     * @return true if the buffer has space left for the given number of bytes to be written.
     */
    boolean isWritable(int size);

    /**
     * Writes a single byte to the buffer and advances the write index by one.
     *
     * @param value
     *      The byte to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeByte(int value);

    /**
     * Writes the contents of the given byte array into the buffer and advances the write index by the
     * length of the given array.
     *
     * @param value
     *      The byte array to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeBytes(byte[] value);

    /**
     * Writes the contents of the given byte array into the buffer and advances the write index by the
     * length value given.
     *
     * @param value
     *      The byte array to write into the buffer.
     * @param length
     *      The number of bytes to write from the given array into this buffer
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeBytes(byte[] value, int length);

    /**
     * Writes the contents of the given byte array into the buffer and advances the write index by the
     * length value given.  The bytes written into this buffer are read starting at the given offset
     * into the passed in byte array.
     *
     * @param value
     *      The byte array to write into the buffer.
     * @param offset
     *      The offset into the given array to start reading from.
     * @param length
     *      The number of bytes to write from the given array into this buffer
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeBytes(byte[] value, int offset, int length);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the current {@code writeIndex} until the source buffer becomes
     * unreadable, and increases the {@code writeIndex} by the number of
     * the transferred bytes.  This method is basically same with
     * {@link #writeBytes(ProtonBuffer, int, int)}, except that this method
     * increases the {@code readIndex} of the source buffer by the number of
     * the transferred bytes while {@link #writeBytes(ProtonBuffer, int, int)}
     * does not.
     *
     * @param source
     *      The source buffer from which the bytes are read.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException
     *         if {@code src.readableBytes} is greater than
     *            {@code this.writableBytes}
     */
    ProtonBuffer writeBytes(ProtonBuffer source);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the current {@code writeIndex} and increases the {@code writeIndex}
     * by the number of the transferred bytes (= {@code length}).  This method
     * is basically same with {@link #writeBytes(ProtonBuffer, int, int)},
     * except that this method increases the {@code readIndex} of the source
     * buffer by the number of the transferred bytes (= {@code length}) while
     * {@link #writeBytes(ProtonBuffer, int, int)} does not.
     *
     * @param source
     *      The source buffer from which the bytes are read.
     * @param length
     *      The number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if {@code length} is greater than {@code this.writableBytes} or
     *         if {@code length} is greater then {@code src.readableBytes}
     */
    ProtonBuffer writeBytes(ProtonBuffer source, int length);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the current {@code writeIndex} and increases the {@code writeIndex}
     * by the number of the transferred bytes (= {@code length}).
     *
     * @param source
     *      The source buffer from which the bytes are read.
     * @param sourrceIndex
     *      The first index of the source
     * @param length
     *      The number of bytes to transfer
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if the specified {@code srcIndex} is less than {@code 0},
     *         if {@code srcIndex + length} is greater than
     *            {@code src.capacity}, or
     *         if {@code length} is greater than {@code this.writableBytes}
     */
    ProtonBuffer writeBytes(ProtonBuffer source, int sourrceIndex, int length);

    /**
     * Transfers the specified source buffer's data to this buffer starting at
     * the current {@code writeIndex} until the source buffer's position
     * reaches its limit, and increases the {@code writeIndex} by the
     * number of the transferred bytes.
     *
     * @param source
     *      The source buffer from which the bytes are read.
     *
     * @return this buffer for chaining
     *
     * @throws IndexOutOfBoundsException
     *         if {@code src.remaining()} is greater than
     *            {@code this.writableBytes}
     */
    ProtonBuffer writeBytes(ByteBuffer source);

    /**
     * Writes a single boolean to the buffer and advances the write index by one.
     *
     * @param value
     *      The boolean to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeBoolean(boolean value);

    /**
     * Writes a single short to the buffer and advances the write index by two.
     *
     * @param value
     *      The short to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeShort(short value);

    /**
     * Writes a single integer to the buffer and advances the write index by four.
     *
     * @param value
     *      The integer to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeInt(int value);

    /**
     * Writes a single long to the buffer and advances the write index by eight.
     *
     * @param value
     *      The long to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeLong(long value);

    /**
     * Writes a single float to the buffer and advances the write index by four.
     *
     * @param value
     *      The float to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeFloat(float value);

    /**
     * Writes a single double to the buffer and advances the write index by eight.
     *
     * @param value
     *      The double to write into the buffer.
     *
     * @return this ProtonBuffer for chaining.
     *
     * @throws IndexOutOfBoundsException if there is no room in the buffer for this write operation.
     */
    ProtonBuffer writeDouble(double value);

}