ByteBuffer (ch-commons-util 6.0.2 API)

java.lang.Object
- com.cloudhopper.commons.util.ByteBuffer

```
public class ByteBuffer
extends Object
```
This class implements a capacity constrained ByteBuffer using a circular array of bytes. A circular array of bytes minimizes memory allocations when adding or removing bytes from the buffer.

NOTE: This class is NOT thread-safe since its intended mainly for use inside a single thread -- such as reading from a socket or other connection.

NOTE: This class does not auto grow the underlying buffer. All add() methods are the only way to copy information to this buffer. However, there are various ways to delete or remove data from this buffer. The delete() methods will erase data from the buffer without returning the removed bytes. This avoids allocating memory if you simply want to free up space in this buffer. The remove() methods will erase the data AND return the erased data as the return value. Use these methods when you need to get the data and delete it. The size of the underlying byte[] buffer is always capacity + 1. If you initialize this buffer requesting a capacity of 1024, please be aware that this class will actually allocate 1025 bytes. This is required to be able to internally track where the data ends inside the buffer. However, externally, it will look like only 1024 bytes are free, capacity, size, etc. At no time would 1025 be made available in a public method.

This class is originally derived from a CircularByteBuffer obtained from http://awr.free.fr/ which was distributed with the Lesser GNU Public License. That class was written by Arnaud Witschger. This class has been heavily modified for a different usage.

Author:

joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Constructor Summary

Constructors
Constructor and Description
`ByteBuffer()` Constructs a new instance of `ByteBuffer` with an initial default capacity of 1024 bytes (DEFAULT_BUFFER_CAPACITY)
`ByteBuffer(byte[] bytes)` Constructs a new instance of `ByteBuffer` with a capacity only large enough to hold they byte array.
`ByteBuffer(byte[] bytes, int capacity)` Constructs a new instance of `ByteBuffer` with the specified capacity.
`ByteBuffer(byte[] bytes, int offset, int length)` Constructs a new instance of `ByteBuffer` with the specified capacity.
`ByteBuffer(byte[] bytes, int offset, int length, int capacity)` Constructs a new instance of `ByteBuffer` with the specified capacity.
`ByteBuffer(int capacity)` Constructs a new instance of `ByteBuffer` with the specified capacity.
`ByteBuffer(String string0)` Constructs a new instance of `ByteBuffer`.
`ByteBuffer(String string0, int capacity)` Constructs a new instance of `ByteBuffer` with the specified capacity.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`add(byte b)` Adds one byte to the buffer and throws an exception if the buffer is full.
`void`	`add(byte[] bytes)` Adds a byte array to this buffer.
`void`	`add(byte[] bytes, int offset, int length)` Adds a byte array to this buffer starting from the offset up to the length requested.
`int`	`capacity()` Gets the total buffer allocated capacity, not the remaining capacity.
`protected static void`	`checkOffsetLength(int bytesLength, int offset, int length)` Helper method for validating if an offset and length are valid for a given byte array.
`void`	`clear()` Clears the buffer and resets it.
`ByteBuffer`	`copy()` Most efficient copy of this `ByteBuffer`.
`ByteBuffer`	`copy(int offset, int length)` Most efficient copy of this `ByteBuffer`.
`ByteBuffer`	`copy(int offset, int length, int capacity)` Most efficient copy of this `ByteBuffer`.
`void`	`delete(int count)` Deletes the first N bytes of the buffer.
`boolean`	`endsWith(byte[] prefix)` Tests if the buffer ends with the bytes array prefix.
`boolean`	`equals(byte[] bytes)` Tests if the current ByteBuffer and the byte array have the same sequence of bytes.
`boolean`	`equals(Object obj)` Tests if the current ByteBuffer and the parameter are both ByteBuffers and whether it contains the same sequence of bytes.
`int`	`free()` Gets the number of free bytes this buffer has remaining for writing.
`byte`	`get(int index)` Gets the byte at the given index relative to the beginning the circular buffer.
`int`	`hashCode()` Gets a hash code for this ByteBuffer object based on actual sequence of bytes stored in this buffer.
`int`	`indexOf(byte[] bytes)` Returns the index within this buffer of the first occurrence of the specified bytes.
`int`	`indexOf(byte[] bytes, int offset)` Returns the index within this buffer of the first occurrence of the specified bytes after the offset.
`boolean`	`isEmpty()` Tests if the buffer is empty.
`boolean`	`isFree(int count)` Tests if the buffer has enough free space to store N bytes.
`boolean`	`isFull()` Tests if the buffer is full.
`int`	`occurrences(byte b)` Counts the number of occurrences of the byte in this `ByteBuffer`.
`int`	`occurrences(byte[] bytes)` Counts the number of occurrences of the byte array in this `ByteBuffer`.
`byte`	`remove()` Removes the first (oldest/head) byte in the buffer.
`byte[]`	`remove(int count)` Removes a byte array of the first N bytes in the buffer.
`int`	`size()` Gets the current buffer size.
`boolean`	`startsWith(byte[] prefix)` Tests if the buffer starts with the byte array prefix.
`byte[]`	`toArray()` Gets a copy of the current buffer as byte array.
`byte[]`	`toArray(int offset, int length)` Gets a copy of the current buffer as byte array, but only copies data starting from an offset and length.
`void`	`toArray(int offset, int length, byte[] targetBuffer, int targetOffset)` Will copy data from this ByteBuffer's buffer into the targetBuffer.
`byte[]`	`toArray(int offset, int length, int capacity)` Gets a copy of the current buffer as byte array, but the new byte[] has the specified capacity.
`String`	`toHexString()` Return a hexidecimal String representation of the current buffer with each byte displayed in a 2 character hexidecimal format.
`String`	`toHexString(int offset, int length)` Return a hexidecimal String representation of the current buffer with each byte displayed in a 2 character hexidecimal format.
`String`	`toString()` Returns a string representation of the current buffer.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - ByteBuffer
```
public ByteBuffer()
```
    Constructs a new instance of ByteBuffer with an initial default capacity of 1024 bytes (DEFAULT_BUFFER_CAPACITY)
  - ByteBuffer
```
public ByteBuffer(int capacity)
           throws IllegalArgumentException
```
    Constructs a new instance of ByteBuffer with the specified capacity.
    
    Parameters:
    capacity - The buffer capacity. Must be >= 1.
    
    Throws:
    
    IllegalArgumentException
  - ByteBuffer
```
public ByteBuffer(byte[] bytes)
```
    Constructs a new instance of ByteBuffer with a capacity only large enough to hold they byte array. Buffer is initialized with the byte[] bytes starting from offset 0 and adding the entire byte aray.
    
    Parameters:
    bytes - The byte array to initialize buffer with
  - ByteBuffer
```
public ByteBuffer(byte[] bytes,
          int capacity)
           throws IllegalArgumentException
```
    Constructs a new instance of ByteBuffer with the specified capacity. Buffer is initialized with the byte[] bytes starting from offset 0 and adding the entire byte aray. Capacity must be >= the length of the byte array.
    
    Parameters:
    bytes - The byte array to initialize buffer with
    capacity - The buffer capacity. Must be >= 1.
    
    Throws:
    
    IllegalArgumentException - Thrown if the capacity is too small
  - ByteBuffer
```
public ByteBuffer(byte[] bytes,
          int offset,
          int length)
           throws IllegalArgumentException
```
    Constructs a new instance of ByteBuffer with the specified capacity. Buffer is initialized with the byte[] bytes starting from offset and added up to length bytes.
    
    Parameters:
    bytes - The byte array to initialize buffer with
    offset - The offset in the byte array to start from
    length - The length starting from offset within the byte array
    
    Throws:
    
    IllegalArgumentException - Thrown if offset or length is negative, capacity is too small, or if the offset+length would cause a read past the length of the byte array.
  - ByteBuffer
```
public ByteBuffer(byte[] bytes,
          int offset,
          int length,
          int capacity)
           throws IllegalArgumentException
```
    Constructs a new instance of ByteBuffer with the specified capacity. Buffer is initialized with the byte[] bytes starting from offset and added up to length bytes. Capacity must be large enough to store the length.
    
    Parameters:
    bytes - The byte array to initialize buffer with
    offset - The offset in the byte array to start from
    length - The length starting from offset within the byte array
    capacity - The buffer capacity. Must be >= 1.
    
    Throws:
    
    IllegalArgumentException - Thrown if offset or length is negative, capacity is too small, or if the offset+length would cause a read past the length of the byte array.
  - ByteBuffer
```
public ByteBuffer(String string0)
           throws IllegalArgumentException
```
    Constructs a new instance of ByteBuffer. Buffer is initialized with the String converted to bytes using the ISO-8859-1 character set.
    
    Parameters:
    string0 - The string to initialize our buffer with
    
    Throws:
    
    IllegalArgumentException - If capacity is too small to store the bytes from the String
  - ByteBuffer
```
public ByteBuffer(String string0,
          int capacity)
           throws IllegalArgumentException
```
    Constructs a new instance of ByteBuffer with the specified capacity. Buffer is initialized with the String converted to bytes using the ISO-8859-1 character set. Capacity must be large enough to store the bytes obtained after conversion. If only 8-bit data is stored in the String, the capacity required would be the length() of the String.
    
    Parameters:
    string0 - The string to initialize our buffer with
    capacity - The capacity of the buffer. Must be >= byte length of string
    
    Throws:
    
    IllegalArgumentException - If capacity is too small to store the bytes from the String
- Method Detail
  - size
```
public int size()
```
    Gets the current buffer size.
    
    Returns:
    The current buffer size.
  - capacity
```
public int capacity()
```
    Gets the total buffer allocated capacity, not the remaining capacity. Using capacity()-size() would calculate how much room is remaining in this buffer.
    
    Returns:
    The buffer capacity.
    See Also:
    free()
  - free
```
public int free()
```
    Gets the number of free bytes this buffer has remaining for writing.
    
    Returns:
    The number of bytes available for writing in this buffer.
  - isFree
```
public boolean isFree(int count)
```
    Tests if the buffer has enough free space to store N bytes. Same as free() >= N.
    
    Returns:
    True if the buffer has enough free space to store N bytes, otherwise false.
  - isEmpty
```
public boolean isEmpty()
```
    Tests if the buffer is empty.
    
    Returns:
    True if the buffer is empty, otherwise false.
  - isFull
```
public boolean isFull()
```
    Tests if the buffer is full.
    
    Returns:
    True if the buffer is full, otherwise false.
  - clear
```
public void clear()
```
    Clears the buffer and resets it. Does not reallocate a new array.
  - add
```
public void add(byte b)
         throws BufferIsFullException
```
    Adds one byte to the buffer and throws an exception if the buffer is full.
    
    Parameters:
    b - Byte to add to the buffer.
    
    Throws:
    
    BufferIsFullException - If the buffer is full and the byte cannot be stored.
  - add
```
public void add(byte[] bytes)
         throws BufferSizeException
```
    Adds a byte array to this buffer. If the free space remaining in the buffer is not large enough, this method will throw a BufferSizeException. A byte array consisting of a length of 0 will immediately return.
    
    Parameters:
    bytes - A byte array to add to this buffer. Its size must less than or equal to this buffer's free space
    
    Throws:
    
    BufferSizeException - If this buffer's free space is not large enough to store add the byte array
  - checkOffsetLength
```
protected static void checkOffsetLength(int bytesLength,
                     int offset,
                     int length)
                                 throws IllegalArgumentException
```
    Helper method for validating if an offset and length are valid for a given byte array. Checks if the offset or length is negative or if the offset+length would cause a read past the end of the byte array.
    
    Parameters:
    bytesLength - The length of the byte array to validate against
    offset - The offset within the byte array
    length - The length to read starting from the offset
    
    Throws:
    
    IllegalArgumentException - If any of the above conditions are violated.
  - add
```
public void add(byte[] bytes,
       int offset,
       int length)
         throws IllegalArgumentException,
                BufferSizeException
```
    Adds a byte array to this buffer starting from the offset up to the length requested. If the free space remaining in the buffer is not large enough, this method will throw a BufferSizeException.
    
    Parameters:
    bytes - A byte array to add to this buffer.
    offset - The offset within the byte array to begin to add
    length - The length starting from offset to begin to add
    
    Throws:
    
    BufferSizeException - If this buffer's free space is not large enough to store add the byte array
    
    IllegalArgumentException
  - delete
```
public void delete(int count)
            throws BufferSizeException
```
    Deletes the first N bytes of the buffer. Avoids allocating any memory since there is no return value for this method. If you want to delete and also see the deleted data as a return value, please use the remove() methods.
    
    Throws:
    
    BufferSizeException
  - remove
```
public byte remove()
            throws BufferIsEmptyException
```
    Removes the first (oldest/head) byte in the buffer. If the buffer is empty, this method will throw a BufferIsEmptyException
    
    Returns:
    The first (oldest/head) byte in the buffer
    
    Throws:
    
    BufferIsEmptyException - If the buffer is empty and a byte cannot be removed.
  - remove
```
public byte[] remove(int count)
              throws BufferSizeException
```
    Removes a byte array of the first N bytes in the buffer. The parameter count must be a value between 1 and the capacity of the buffer, otherwise a runtime IllegalArgumentException will be thrown. If the N bytes requested is larger than the buffer size, then a BufferSizeException will be thrown.
    
    Parameters:
    count - The number of bytes to remove (a value between 1 and the buffer capacity).
    
    Returns:
    The first N bytes of the buffer.
    
    Throws:
    
    BufferSizeException - If the buffer is not large enough to fufill the request (if N is > size)
  - occurrences
```
public int occurrences(byte b)
```
    Counts the number of occurrences of the byte in this ByteBuffer. This method will not overlap any bytes during its search. For example, if you're search for bytes of "AA" in a buffer containing "AAA", this method will only return a value of 1.
    
    Parameters:
    b - The byte to search for
    
    Returns:
    -1 if byte is not found, otherwise the number of occurrences.
  - occurrences
```
public int occurrences(byte[] bytes)
```
    Counts the number of occurrences of the byte array in this ByteBuffer. This method will not overlap any bytes during its search. For example, if you're search for bytes of "AA" in a buffer containing "AAA", this method will only return a value of 1.
    
    Parameters:
    bytes - The byte[] to search for
    
    Returns:
    -1 if bytes is a length of zero, otherwise the number of occurrences.
  - copy
```
public ByteBuffer copy()
```
    Most efficient copy of this ByteBuffer. The internal buffer is copied to the new ByteBuffer using either 1 or 2 calls to System.arraycopy().
    
    Returns:
    The new ByteBuffer with copied data
  - copy
```
public ByteBuffer copy(int offset,
              int length)
```
    Most efficient copy of this ByteBuffer. The internal buffer is copied to the new ByteBuffer using either 1 or 2 calls to System.arraycopy().
    
    Parameters:
    offset - The offset in the buffer to start from
    length - The length from the offset
    
    Returns:
    The new ByteBuffer with copied data
  - copy
```
public ByteBuffer copy(int offset,
              int length,
              int capacity)
```
    Most efficient copy of this ByteBuffer. The internal buffer is copied to the new ByteBuffer using either 1 or 2 calls to System.arraycopy().
    
    Parameters:
    offset - The offset in the buffer to start from
    length - The length from the offset
    capacity - The capacity of the new ByteBuffer. Must be >= this ByteBuffer's size()
    
    Returns:
    The new ByteBuffer with copied data
  - get
```
public byte get(int index)
         throws IllegalArgumentException,
                BufferSizeException
```
    Gets the byte at the given index relative to the beginning the circular buffer. The index must be a value between 0 and the buffer capacity.
    
    Parameters:
    index - The index of the byte relative to the beginning the buffer (a value between 0 and the the current size).
    
    Returns:
    The byte at the given position relative to the beginning the buffer.
    
    Throws:
    
    BufferSizeException - If the index is >= size()
    
    IllegalArgumentException
  - toArray
```
public byte[] toArray()
```
    Gets a copy of the current buffer as byte array. Method will allocate only enough memory to hold a copy of the current buffer data.
    
    Returns:
    A byte array. Could be empty if this buffer's size() is zero.
  - toArray
```
public byte[] toArray(int offset,
             int length)
```
    Gets a copy of the current buffer as byte array, but only copies data starting from an offset and length. Method will allocate only enough memory to hold a copy of the slice of the current buffer data.
    
    Parameters:
    offset - The offset to start from
    length - The length from the offset
    
    Returns:
    A byte array. Could be empty.
    
    Throws:
    
    IllegalArgumentException - If capacity isn't large enough enough to hold the new byte[]
  - toArray
```
public byte[] toArray(int offset,
             int length,
             int capacity)
```
    Gets a copy of the current buffer as byte array, but the new byte[] has the specified capacity. Useful if you need to store additional bytes in the returned byte[] and dont' want to do an additional System.arraycopy() afterwards. Method will allocate memory to hold a copy of the current array and return it.
    
    Parameters:
    offset - The offset to start from
    length - The length from the offset
    capacity - The size of the new byte[]. Must be >= this buffer's size()
    
    Returns:
    A byte array. Could be empty.
    
    Throws:
    
    IllegalArgumentException - If capacity isn't large enough enough to hold the new byte[]
  - toArray
```
public void toArray(int offset,
           int length,
           byte[] targetBuffer,
           int targetOffset)
```
    Will copy data from this ByteBuffer's buffer into the targetBuffer. This method requires the targetBuffer to already be allocated with enough capacity to hold this ByteBuffer's data.
    
    Parameters:
    offset - The offset within the ByteBuffer to start copy from
    length - The length from the offset to copy
    targetBuffer - The target byte array we'll copy data into. Must already be allocated with enough capacity.
    targetOffset - The offset within the target byte array to start from
    
    Throws:
    
    IllegalArgumentException - If the offset and length are invalid for this ByteBuffer, if the targetOffset and targetLength are invalid for the targetBuffer, or if if the targetBuffer's capacity is not large enough to hold the copied data.
  - startsWith
```
public boolean startsWith(byte[] prefix)
```
    Tests if the buffer starts with the byte array prefix. The byte array prefix must have a size >= this buffer's size.
    
    Returns:
    True if the buffer starts with the bytes array, otherwise false.
  - endsWith
```
public boolean endsWith(byte[] prefix)
```
    Tests if the buffer ends with the bytes array prefix. The byte array prefix must have a size >= this buffer's size.
    
    Returns:
    True if the buffer ends with the bytes array, otherwise false.
  - indexOf
```
public int indexOf(byte[] bytes)
```
    Returns the index within this buffer of the first occurrence of the specified bytes. The bytes to search for must have a size lower than or equal to the current buffer size. This method will return -1 if the bytes are not contained within this byte buffer.
    
    Parameters:
    bytes - The byte array to search for
    
    Returns:
    The index where the bytes start to match within the buffer.
  - indexOf
```
public int indexOf(byte[] bytes,
          int offset)
```
    Returns the index within this buffer of the first occurrence of the specified bytes after the offset. The bytes to search for must have a size lower than or equal to the current buffer size. This method will return -1 if the bytes are not contained within this byte buffer.
    
    Parameters:
    bytes - The byte array to search for
    offset - The offset within the buffer to search from
    
    Returns:
    The index where the bytes start to match within the buffer.
  - hashCode
```
public int hashCode()
```
    Gets a hash code for this ByteBuffer object based on actual sequence of bytes stored in this buffer. That means this object is safe to store in Hashtables or Hashmaps since the same sequence of bytes in different instances will generate the same hashCode, regardless of capacity, internal read position, write position, etc.
    This method is implemented using logic from Jakarta Commons Lang library in the HashCodeBuilder class.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    A hash code for this ByteBuffer object for the sequence of bytes stored in this buffer.
  - equals
```
public boolean equals(Object obj)
```
    Tests if the current ByteBuffer and the parameter are both ByteBuffers and whether it contains the same sequence of bytes.
    
    Overrides:
    
    equals in class Object
    
    Returns:
    True if the two objects are equal and contain the same sequence of bytes, otherwise false.
  - equals
```
public boolean equals(byte[] bytes)
```
    Tests if the current ByteBuffer and the byte array have the same sequence of bytes. Nearly the same as calling startsWith(), but if the two byte[]'s are a length of zero, this method will return true.
    
    Returns:
    True if the two byte arrays are equal and contain the same sequence of bytes, otherwise false.
  - toString
```
public String toString()
```
    Returns a string representation of the current buffer. This converts any internal stored bytes directly to chars and appends them to a String.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    A byte-to-char string representation of the current buffer.
  - toHexString
```
public String toHexString()
```
    Return a hexidecimal String representation of the current buffer with each byte displayed in a 2 character hexidecimal format. Useful for debugging. Convert a ByteBuffer to a String with a hexidecimal format.
    
    Returns:
    The string in hex representation
  - toHexString
```
public String toHexString(int offset,
                 int length)
```
    Return a hexidecimal String representation of the current buffer with each byte displayed in a 2 character hexidecimal format. Useful for debugging. Convert a ByteBuffer to a String with a hexidecimal format.
    
    Parameters:
    offset -
    length -
    
    Returns:
    The string in hex representation

Class ByteBuffer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ByteBuffer

ByteBuffer

ByteBuffer

ByteBuffer

ByteBuffer

ByteBuffer

ByteBuffer

ByteBuffer

Method Detail

size

capacity

free

isFree

isEmpty

isFull

clear

add

add

checkOffsetLength

add

delete

remove

remove

occurrences

occurrences

copy

copy

copy

get

toArray

toArray

toArray

toArray

startsWith

endsWith

indexOf

indexOf

hashCode

equals

equals

toString

toHexString

toHexString