Package org.apache.qpid.protonj2.buffer

Class ProtonBufferUtils

java.lang.Object
org.apache.qpid.protonj2.buffer.ProtonBufferUtils
public abstract class ProtonBufferUtils extends Object
Set of Utility methods useful when dealing with byte arrays and other primitive types.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAX_BUFFER_CAPACITY
    The maximum buffer size that allows for JDK byte reservations on buffer size or addresses.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ProtonBufferUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    checkArgumentIsNotNegative(int value, String description)
    Checks the argument to determine if it less than zero and throws if it is.
    static void
    checkArgumentIsNotNegative(long value, String description)
    Checks the argument to determine if it less than zero and throws if it is.
    static void
    checkBufferCanGrowTo(int currentCapacity, int additional)
    Checks if a buffer can grow buffer the given amount or if that would exceed the maximum allowed buffer size.
    static void
    checkImplicitGrowthLimit(int implicitCapacity, int currentCapacity)
    Checks the implicit growth limit value for buffer implementations
    static void
    checkIndexIsNotNegative(int value, String description)
    Checks the index to determine if it less than zero and throws if it is.
    static void
    checkIndexIsNotNegative(long value, String description)
    Checks the index to determine if it less than zero and throws if it is.
    static void
    checkIsClosed(ProtonBuffer buffer)
    Checks the given ProtonBuffer to see if it has already been closed.
    static void
    checkIsNotNegative(int value, String description)
    Checks the value to determine if it less than zero and throws if it is.
    static void
    checkIsNotNegative(long value, String description)
    Checks the value to determine if it less than zero and throws if it is.
    static void
    checkIsReadOnly(ProtonBuffer buffer)
    Checks the given ProtonBuffer to see if it has already been closed.
    static void
    checkLength(int length)
    Checks the length value is not negative and throws an exception if it is.
    static void
    checkOffset(int offset)
    Checks the offset value is not negative and throws an exception if it is.
    static int
    compare(ProtonBuffer lhs, ProtonBuffer rhs)
    Compares two ProtonBuffer instances.
    static CharSequence
    copyToCharSequence(ProtonBuffer source, int offset, int length, Charset charset)
    Copies the given length number of bytes from the provided buffer and returns a CharSequence that is comprised of the characters of that sequence using the provided Charset to make the transformation.
    static boolean
    equals(ProtonBuffer left, int leftStartIndex, ProtonBuffer right, int rightStartIndex, int length)
    Compares two ProtonBuffer instances for equality.
    static boolean
    equals(ProtonBuffer left, ProtonBuffer right)
    Compares two ProtonBuffer instances for equality.
    static boolean
    equals(ProtonBuffer left, ProtonBuffer right, int length)
    Compares two ProtonBuffer instances for equality.
    static ProtonBufferClosedException
    genericBufferIsClosed(ProtonBuffer buffer)
     
    static ProtonBufferReadOnlyException
    genericBufferIsReadOnly(ProtonBuffer buffer)
     
    static IndexOutOfBoundsException
    genericOutOfBounds(ProtonBuffer buffer, int index)
     
    static Cleaner
    getCleaner()
    Create and / or return a Cleaner instance on demand and then serve out only that instance from then on.
    static int
    hashCode(ProtonBuffer buffer)
    Compute a hash code from the given ProtonBuffer.
    static byte
    readByte(byte[] array, int offset)
    Reads a single byte from the given array from the provided offset.
    static char
    readChar(byte[] array, int offset)
    Reads a two byte UTF-16 character from the given array from the provided offset.
    static CharSequence
    readCharSequence(ProtonBuffer source, int length, Charset charset)
    Reads a CharSequence from the given ProtonBuffer advancing the read offset by the length value provided.
    static double
    readDouble(byte[] array, int offset)
    Reads an eight byte double precision value from the given array from the provided offset.
    static float
    readFloat(byte[] array, int offset)
    Reads a four byte floating point value from the given array from the provided offset.
    static int
    readInt(byte[] array, int offset)
    Reads a four byte integer from the given array from the provided offset.
    static long
    readLong(byte[] array, int offset)
    Reads an eight byte integer from the given array from the provided offset.
    static short
    readShort(byte[] array, int offset)
    Reads a two byte short from the given array from the provided offset.
    static int
    readUnsignedByte(byte[] array, int offset)
    Reads a single byte from the given array from the provided offset and returns it as an integer that represents the unsigned byte value.
    static long
    readUnsignedInt(byte[] array, int offset)
    Reads a four byte integer from the given array from the provided offset.
    static int
    readUnsignedShort(byte[] array, int offset)
    Reads a two byte short from the given array from the provided offset and return it in an integer value that represents the unsigned short value.
    static Cleaner.Cleanable
    registerCleanup(Object observed, ProtonBuffer buffer)
    Register a cleanup watch on the given object which is related to the ProtonBuffer provided and ensure that if the object does not close the buffer by the time it becomes unreachable that the buffer is closed.
    static void
    setCleaner(Cleaner cleaner)
    Allows an external application Cleaner instance to be assigned to the buffer utilities Cleaner instance which will then be used if a cleaner for a ProtonBuffer is registered.
    static byte[]
    toByteArray(byte value)
    Given a byte value returns an array containing the given byte as the only entry.
    static byte[]
    toByteArray(int value)
    Given an integer value returns an array containing the given byte as the only entry.
    static byte[]
    toByteArray(long value)
    Given a long value returns an array containing the given byte as the only entry.
    static byte[]
    toByteArray(short value)
    Given a short value returns an array containing the given byte as the only entry.
    static byte[]
    toByteArray(ByteBuffer buffer)
    Given a ByteBuffer returns an array containing a copy of the readable bytes from the provided buffer.
    static byte[]
    toByteArray(ProtonBuffer buffer)
    Given a ProtonBuffer returns an array containing a deep copy of the readable bytes from the provided buffer.
    static ByteBuffer
    toByteBuffer(ProtonBuffer buffer)
    Given a ProtonBuffer returns an ByteBuffer containing a copy of the readable bytes from the provided buffer.
    static String
    toString(ProtonBuffer buffer, Charset charset)
    Create a new String that is a copy of the boffer's readable bytes and is defined by the Charset provided.
    static ProtonBufferAllocator
    unclosable(ProtonBufferAllocator allocator)
    Creates a wrapper around the given allocator that prevents the close call from having any effect.
    static byte[]
    writeByte(byte value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeChar(char value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeDouble(double value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeFloat(float value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeInt(int value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeLong(long value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeShort(short value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeUnsignedByte(int value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeUnsignedInt(long value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.
    static byte[]
    writeUnsignedShort(int value, byte[] destination, int offset)
    Writes the value given into the provided array at the specified offset returning to destination once done.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MAX_BUFFER_CAPACITY

      public static final int MAX_BUFFER_CAPACITY
      The maximum buffer size that allows for JDK byte reservations on buffer size or addresses.
      See Also:

  • Constructor Details

    • ProtonBufferUtils

      public ProtonBufferUtils()

  • Method Details

    • getCleaner

      public static Cleaner getCleaner()
      Create and / or return a Cleaner instance on demand and then serve out only that instance from then on.

      Care should be taken when using Cleaners as the instance will be tired to a thread that will run to perform the cleanups, an application is advised to assign a single global value for the whole application,

      Returns:
      a Cleaner instance which is created on demand or was already assigned.

    • setCleaner

      public static void setCleaner(Cleaner cleaner)
      Allows an external application Cleaner instance to be assigned to the buffer utilities Cleaner instance which will then be used if a cleaner for a ProtonBuffer is registered.
      Parameters:
      cleaner - The cleaner to assign as the global Cleaner for buffer instances.

    • registerCleanup

      public static Cleaner.Cleanable registerCleanup(Object observed, ProtonBuffer buffer)
      Register a cleanup watch on the given object which is related to the ProtonBuffer provided and ensure that if the object does not close the buffer by the time it becomes unreachable that the buffer is closed.
      Parameters:
      observed - The resource holder that if unreachable should release the given buffer
      buffer - The buffer to be closed when the observed object is unreachable.
      Returns:
      a Cleaner instance the caller can invoke explicitly.

    • toString

      public static String toString(ProtonBuffer buffer, Charset charset)
      Create a new String that is a copy of the boffer's readable bytes and is defined by the Charset provided.
      Parameters:
      buffer - The buffer to convert to a string
      charset - The charset to use when creating the new string.
      Returns:
      a String that is a view of the given buffer's readable bytes.

    • toByteArray

      public static byte[] toByteArray(ProtonBuffer buffer)
      Given a ProtonBuffer returns an array containing a deep copy of the readable bytes from the provided buffer.
      Parameters:
      buffer - The buffer whose readable bytes are to be copied.
      Returns:
      a new array containing a copy of the readable bytes from the buffer.

    • toByteArray

      public static byte[] toByteArray(ByteBuffer buffer)
      Given a ByteBuffer returns an array containing a copy of the readable bytes from the provided buffer.
      Parameters:
      buffer - The buffer whose readable bytes are to be copied.
      Returns:
      a new array containing a copy of the readable bytes from the buffer.

    • toByteBuffer

      public static ByteBuffer toByteBuffer(ProtonBuffer buffer)
      Given a ProtonBuffer returns an ByteBuffer containing a copy of the readable bytes from the provided buffer.
      Parameters:
      buffer - The buffer whose readable bytes are to be copied.
      Returns:
      a new ByteBuffer containing a copy of the readable bytes from the buffer.

    • toByteArray

      public static byte[] toByteArray(byte value)
      Given a byte value returns an array containing the given byte as the only entry.
      Parameters:
      value - The value to wrap in an array instance.
      Returns:
      a new array containing the primitive value as the only array element.

    • toByteArray

      public static byte[] toByteArray(short value)
      Given a short value returns an array containing the given byte as the only entry.
      Parameters:
      value - The value to wrap in an array instance.
      Returns:
      a new array containing the primitive value as the only array element.

    • toByteArray

      public static byte[] toByteArray(int value)
      Given an integer value returns an array containing the given byte as the only entry.
      Parameters:
      value - The value to wrap in an array instance.
      Returns:
      a new array containing the primitive value as the only array element.

    • toByteArray

      public static byte[] toByteArray(long value)
      Given a long value returns an array containing the given byte as the only entry.
      Parameters:
      value - The value to wrap in an array instance.
      Returns:
      a new array containing the primitive value as the only array element.

    • writeChar

      public static byte[] writeChar(char value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeByte

      public static byte[] writeByte(byte value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeUnsignedByte

      public static byte[] writeUnsignedByte(int value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeShort

      public static byte[] writeShort(short value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeUnsignedShort

      public static byte[] writeUnsignedShort(int value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeInt

      public static byte[] writeInt(int value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeUnsignedInt

      public static byte[] writeUnsignedInt(long value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeLong

      public static byte[] writeLong(long value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeFloat

      public static byte[] writeFloat(float value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • writeDouble

      public static byte[] writeDouble(double value, byte[] destination, int offset)
      Writes the value given into the provided array at the specified offset returning to destination once done. The provided array must have enough space starting from the given offset for the value to be encoded or an exception will be thrown.
      Parameters:
      value - The value to be encoded into the given array
      destination - The given array where the provided value should be written.
      offset - The offset into the array to start writing.
      Returns:
      the provided destination array.

    • readByte

      public static byte readByte(byte[] array, int offset)
      Reads a single byte from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readUnsignedByte

      public static int readUnsignedByte(byte[] array, int offset)
      Reads a single byte from the given array from the provided offset and returns it as an integer that represents the unsigned byte value.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readShort

      public static short readShort(byte[] array, int offset)
      Reads a two byte short from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readUnsignedShort

      public static int readUnsignedShort(byte[] array, int offset)
      Reads a two byte short from the given array from the provided offset and return it in an integer value that represents the unsigned short value.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readChar

      public static char readChar(byte[] array, int offset)
      Reads a two byte UTF-16 character from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readInt

      public static int readInt(byte[] array, int offset)
      Reads a four byte integer from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readUnsignedInt

      public static long readUnsignedInt(byte[] array, int offset)
      Reads a four byte integer from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readLong

      public static long readLong(byte[] array, int offset)
      Reads an eight byte integer from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readFloat

      public static float readFloat(byte[] array, int offset)
      Reads a four byte floating point value from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • readDouble

      public static double readDouble(byte[] array, int offset)
      Reads an eight byte double precision value from the given array from the provided offset.
      Parameters:
      array - The array to be read from
      offset - The offset into the array to start reading from.
      Returns:
      the resulting value read from the array at the provided array offset.

    • checkLength

      public static void checkLength(int length)
      Checks the length value is not negative and throws an exception if it is.
      Parameters:
      length - The length value to be validated

    • checkIsNotNegative

      public static void checkIsNotNegative(int value, String description)
      Checks the value to determine if it less than zero and throws if it is.
      Parameters:
      value - The length value to be validated
      description - A description value appended to the exception string.

    • checkIsNotNegative

      public static void checkIsNotNegative(long value, String description)
      Checks the value to determine if it less than zero and throws if it is.
      Parameters:
      value - The length value to be validated
      description - A description value appended to the exception string.

    • checkIndexIsNotNegative

      public static void checkIndexIsNotNegative(int value, String description)
      Checks the index to determine if it less than zero and throws if it is.
      Parameters:
      value - The index value to be validated
      description - A description value appended to the exception string.

    • checkIndexIsNotNegative

      public static void checkIndexIsNotNegative(long value, String description)
      Checks the index to determine if it less than zero and throws if it is.
      Parameters:
      value - The index value to be validated
      description - A description value appended to the exception string.

    • checkArgumentIsNotNegative

      public static void checkArgumentIsNotNegative(int value, String description)
      Checks the argument to determine if it less than zero and throws if it is.
      Parameters:
      value - The argument value to be validated
      description - A description value appended to the exception string.

    • checkArgumentIsNotNegative

      public static void checkArgumentIsNotNegative(long value, String description)
      Checks the argument to determine if it less than zero and throws if it is.
      Parameters:
      value - The argument value to be validated
      description - A description value appended to the exception string.

    • checkOffset

      public static void checkOffset(int offset)
      Checks the offset value is not negative and throws an exception if it is.
      Parameters:
      offset - The offset value to be validated

    • checkIsClosed

      public static void checkIsClosed(ProtonBuffer buffer)
      Checks the given ProtonBuffer to see if it has already been closed.
      Parameters:
      buffer - The buffer to check if closed

    • checkIsReadOnly

      public static void checkIsReadOnly(ProtonBuffer buffer)
      Checks the given ProtonBuffer to see if it has already been closed.
      Parameters:
      buffer - The buffer to check if closed

    • checkBufferCanGrowTo

      public static void checkBufferCanGrowTo(int currentCapacity, int additional)
      Checks if a buffer can grow buffer the given amount or if that would exceed the maximum allowed buffer size.
      Parameters:
      currentCapacity - The buffer's current capacity.
      additional - The amount of new space that will be added to the buffer.

    • checkImplicitGrowthLimit

      public static void checkImplicitGrowthLimit(int implicitCapacity, int currentCapacity)
      Checks the implicit growth limit value for buffer implementations
      Parameters:
      implicitCapacity - The intended implicit growth limit to assign
      currentCapacity - The current buffer capacity

    • genericBufferIsClosed

      public static ProtonBufferClosedException genericBufferIsClosed(ProtonBuffer buffer)

    • genericBufferIsReadOnly

      public static ProtonBufferReadOnlyException genericBufferIsReadOnly(ProtonBuffer buffer)

    • genericOutOfBounds

      public static IndexOutOfBoundsException genericOutOfBounds(ProtonBuffer buffer, int index)

    • equals

      public static boolean equals(ProtonBuffer left, ProtonBuffer right)
      Compares two ProtonBuffer instances for equality.
      Parameters:
      left - The left hand side buffer to compare.
      right - The right hand side buffer to compare.
      Returns:
      true if both buffers are equal.

    • equals

      public static boolean equals(ProtonBuffer left, ProtonBuffer right, int length)
      Compares two ProtonBuffer instances for equality.
      Parameters:
      left - The left hand side buffer to compare.
      right - The right hand side buffer to compare.
      length - The number of bytes in the two buffers to compare.
      Returns:
      true if both buffers are equal.

    • equals

      public static boolean equals(ProtonBuffer left, int leftStartIndex, ProtonBuffer right, int rightStartIndex, int length)
      Compares two ProtonBuffer instances for equality.
      Parameters:
      left - The left hand side buffer to compare.
      leftStartIndex - The index in the readable bytes of the left buffer to start the comparison
      right - The right hand side buffer to compare.
      rightStartIndex - The index in the readable bytes of the right buffer to start the comparison
      length - The number of bytes in the two buffers to compare.
      Returns:
      true if both buffers are equal.

    • hashCode

      public static int hashCode(ProtonBuffer buffer)
      Compute a hash code from the given ProtonBuffer.
      Parameters:
      buffer - The buffer to compute the hash code for.
      Returns:
      the computed hash code for the given buffer

    • compare

      public static int compare(ProtonBuffer lhs, ProtonBuffer rhs)
      Compares two ProtonBuffer instances.
      Parameters:
      lhs - The left hand side buffer to compare
      rhs - The right hand side buffer to compare.
      Returns:
      the value 0 if x == y; a value less than 0 if x < y; and a value greater than 0 if x > y.

    • readCharSequence

      public static CharSequence readCharSequence(ProtonBuffer source, int length, Charset charset)
      Reads a CharSequence from the given ProtonBuffer advancing the read offset by the length value provided.
      Parameters:
      source - The ProtonBuffer that will provide the bytes to create the CharSequence.
      length - The number of bytes to copy starting at the given offset.
      charset - The Charset to use to create the returned CharSequence.
      Returns:
      a CharSequence that is made up of the copied bytes using the provided Charset.

    • copyToCharSequence

      public static CharSequence copyToCharSequence(ProtonBuffer source, int offset, int length, Charset charset)
      Copies the given length number of bytes from the provided buffer and returns a CharSequence that is comprised of the characters of that sequence using the provided Charset to make the transformation.
      Parameters:
      source - The ProtonBuffer that will provide the bytes to create the CharSequence.
      offset - The offset into the given buffer where the copy of bytes should be started from.
      length - The number of bytes to copy starting at the given offset.
      charset - The Charset to use to create the returned CharSequence.
      Returns:
      a CharSequence that is made up of the copied bytes using the provided Charset.

    • unclosable

      public static ProtonBufferAllocator unclosable(ProtonBufferAllocator allocator)
      Creates a wrapper around the given allocator that prevents the close call from having any effect.

      Care should be taken to ensure that the allocator being wrapper is safe to leave unclosed or that the code closes it purposefully in some other context as certain wrapped allocators might require a close to free native resources.

      Parameters:
      allocator - the ProtonBufferAllocator to wrap.
      Returns:
      a buffer allocator that cannot be closed.