Class BufferUtils


  • public final class BufferUtils
    extends java.lang.Object
    General utilities for working with byte-encoded data.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private BufferUtils()
      Private Constructor
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <A extends java.lang.Appendable>
      A
      appendHex​(A sb, byte[] array, int offset, int len, char sep)  
      static <A extends java.lang.Appendable>
      A
      appendHex​(A sb, char sep, byte... array)  
      static <B extends Buffer>
      B
      clear​(B buffer)
      static byte[] decodeHex​(char separator, java.lang.CharSequence csq)  
      static byte[] decodeHex​(char separator, java.lang.CharSequence csq, int start, int end)  
      static <S extends java.io.OutputStream>
      int
      decodeHex​(S stream, char separator, java.lang.CharSequence csq)  
      static <S extends java.io.OutputStream>
      int
      decodeHex​(S stream, char separator, java.lang.CharSequence csq, int start, int end)  
      static void dumpHex​(SimplifiedLog logger, java.util.logging.Level level, java.lang.String prefix, char sep, int chunkSize, byte... data)  
      static void dumpHex​(SimplifiedLog logger, java.util.logging.Level level, java.lang.String prefix, char sep, int chunkSize, byte[] data, int offset, int len)  
      static void dumpHex​(SimplifiedLog logger, java.util.logging.Level level, java.lang.String prefix, PropertyResolver resolver, char sep, byte... data)  
      static void dumpHex​(SimplifiedLog logger, java.util.logging.Level level, java.lang.String prefix, PropertyResolver resolver, char sep, byte[] data, int offset, int len)  
      static boolean equals​(byte[] a1, byte[] a2)
      Compares the contents of 2 arrays of bytes - Note: do not use it to execute security related comparisons (e.g.
      static boolean equals​(byte[] a1, int a1Offset, byte[] a2, int a2Offset, int length)
      Compares the contents of 2 arrays of bytes - Note: do not use it to execute security related comparisons (e.g.
      static byte fromHex​(char hi, char lo)  
      static java.math.BigInteger fromMPIntBytes​(byte[] mpInt)  
      static long getLong​(byte[] buf, int off, int len)  
      static int getNextPowerOf2​(int value)  
      static long getUInt​(byte... buf)  
      static long getUInt​(byte[] buf, int off, int len)  
      static int indexOf​(byte[] array, byte valueToFind, int startIndex, int len)
      Finds the index of the given value in the array starting at the given index and checking up to specified number of elements.
      static boolean isValidInt32Value​(long value)  
      static boolean isValidUint32Value​(long value)  
      static int putLong​(long value, byte[] buf, int off, int len)  
      static int putUInt​(long value, byte[] buf)
      Writes a 32-bit value in network order (i.e., MSB 1st)
      static int putUInt​(long value, byte[] buf, int off, int len)
      Writes a 32-bit value in network order (i.e., MSB 1st)
      static int readInt​(java.io.InputStream input, byte[] buf)
      Read a 32-bit value in network order
      static int readInt​(java.io.InputStream input, byte[] buf, int offset, int len)
      Read a 32-bit value in network order
      static long readUInt​(java.io.InputStream input, byte[] buf)
      Read a 32-bit value in network order
      static long readUInt​(java.io.InputStream input, byte[] buf, int offset, int len)
      Read a 32-bit value in network order
      static java.lang.String toHex​(byte... array)  
      static java.lang.String toHex​(byte[] array, int offset, int len)  
      static java.lang.String toHex​(byte[] array, int offset, int len, char sep)  
      static java.lang.String toHex​(char sep, byte... array)  
      static int updateLengthPlaceholder​(Buffer buffer, int lenPos)
      Used for encodings where we don't know the data length before adding it to the buffer.
      static void updateLengthPlaceholder​(Buffer buffer, int lenPos, long dataLength)
      Updates a 32-bit "placeholder" location for data length - moves the write position to the specified placeholder position, updates the length value and then moves the write position it back to its original value.
      static long validateInt32Value​(long value, java.lang.String message)  
      static long validateInt32Value​(long value, java.lang.String format, java.lang.Object arg)  
      static long validateInt32Value​(long value, java.lang.String format, java.lang.Object... args)  
      static long validateUint32Value​(long value, java.lang.String message)  
      static long validateUint32Value​(long value, java.lang.String format, java.lang.Object arg)  
      static long validateUint32Value​(long value, java.lang.String format, java.lang.Object... args)  
      static void writeInt​(java.io.OutputStream output, int value, byte[] buf)
      Writes a 32-bit value in network order (i.e., MSB 1st)
      static void writeInt​(java.io.OutputStream output, int value, byte[] buf, int off, int len)
      Writes a 32-bit value in network order (i.e., MSB 1st)
      static void writeUInt​(java.io.OutputStream output, long value, byte[] buf)
      Writes a 32-bit value in network order (i.e., MSB 1st)
      static void writeUInt​(java.io.OutputStream output, long value, byte[] buf, int off, int len)
      Writes a 32-bit value in network order (i.e., MSB 1st)
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEFAULT_HEXDUMP_LEVEL

        public static final java.util.logging.Level DEFAULT_HEXDUMP_LEVEL
      • DEFAULT_BUFFER_GROWTH_FACTOR

        public static final java.util.function.IntUnaryOperator DEFAULT_BUFFER_GROWTH_FACTOR
      • MAX_UINT32_VALUE

        public static final long MAX_UINT32_VALUE
        Maximum value of a uint32 field
        See Also:
        Constant Field Values
      • MAX_UINT8_VALUE

        public static final int MAX_UINT8_VALUE
        Maximum value of a uint8 field
        See Also:
        Constant Field Values
    • Constructor Detail

      • BufferUtils

        private BufferUtils()
        Private Constructor
    • Method Detail

      • indexOf

        public static int indexOf​(byte[] array,
                                  byte valueToFind,
                                  int startIndex,
                                  int len)

        Finds the index of the given value in the array starting at the given index and checking up to specified number of elements.

        This method returns -1) for a null input array.

        A negative startIndex is treated as zero. A startIndex larger than the array length will return -1.

        Parameters:
        array - the array to search through for the object, may be null
        valueToFind - the value to find
        startIndex - the index to start searching at
        len - the number of elements to search from the start index
        Returns:
        the index of the value within the array, -1 if not found or null array input or non-positive number of elements
      • dumpHex

        public static void dumpHex​(SimplifiedLog logger,
                                   java.util.logging.Level level,
                                   java.lang.String prefix,
                                   PropertyResolver resolver,
                                   char sep,
                                   byte... data)
      • dumpHex

        public static void dumpHex​(SimplifiedLog logger,
                                   java.util.logging.Level level,
                                   java.lang.String prefix,
                                   PropertyResolver resolver,
                                   char sep,
                                   byte[] data,
                                   int offset,
                                   int len)
      • dumpHex

        public static void dumpHex​(SimplifiedLog logger,
                                   java.util.logging.Level level,
                                   java.lang.String prefix,
                                   char sep,
                                   int chunkSize,
                                   byte... data)
      • dumpHex

        public static void dumpHex​(SimplifiedLog logger,
                                   java.util.logging.Level level,
                                   java.lang.String prefix,
                                   char sep,
                                   int chunkSize,
                                   byte[] data,
                                   int offset,
                                   int len)
      • toHex

        public static java.lang.String toHex​(byte... array)
      • toHex

        public static java.lang.String toHex​(char sep,
                                             byte... array)
      • toHex

        public static java.lang.String toHex​(byte[] array,
                                             int offset,
                                             int len)
      • toHex

        public static java.lang.String toHex​(byte[] array,
                                             int offset,
                                             int len,
                                             char sep)
      • appendHex

        public static <A extends java.lang.Appendable> A appendHex​(A sb,
                                                                   char sep,
                                                                   byte... array)
                                                            throws java.io.IOException
        Throws:
        java.io.IOException
      • appendHex

        public static <A extends java.lang.Appendable> A appendHex​(A sb,
                                                                   byte[] array,
                                                                   int offset,
                                                                   int len,
                                                                   char sep)
                                                            throws java.io.IOException
        Throws:
        java.io.IOException
      • decodeHex

        public static byte[] decodeHex​(char separator,
                                       java.lang.CharSequence csq)
        Parameters:
        separator - The separator between the HEX values - may be EMPTY_HEX_SEPARATOR
        csq - The CharSequence containing the HEX encoded bytes
        Returns:
        The decoded bytes
        Throws:
        java.lang.IllegalArgumentException - If invalid HEX sequence length
        java.lang.NumberFormatException - If invalid HEX characters found
        See Also:
        decodeHex(char, CharSequence, int, int)
      • decodeHex

        public static byte[] decodeHex​(char separator,
                                       java.lang.CharSequence csq,
                                       int start,
                                       int end)
        Parameters:
        separator - The separator between the HEX values - may be EMPTY_HEX_SEPARATOR
        csq - The CharSequence containing the HEX encoded bytes
        start - Start offset of the HEX sequence (inclusive)
        end - End offset of the HEX sequence (exclusive)
        Returns:
        The decoded bytes
        Throws:
        java.lang.IllegalArgumentException - If invalid HEX sequence length
        java.lang.NumberFormatException - If invalid HEX characters found
      • decodeHex

        public static <S extends java.io.OutputStream> int decodeHex​(S stream,
                                                                     char separator,
                                                                     java.lang.CharSequence csq)
                                                              throws java.io.IOException
        Type Parameters:
        S - The OutputStream generic type
        Parameters:
        stream - The target OutputStream
        separator - The separator between the HEX values - may be EMPTY_HEX_SEPARATOR
        csq - The CharSequence containing the HEX encoded bytes
        Returns:
        The number of bytes written to the stream
        Throws:
        java.io.IOException - If failed to write
        java.lang.IllegalArgumentException - If invalid HEX sequence length
        java.lang.NumberFormatException - If invalid HEX characters found
        See Also:
        decodeHex(OutputStream, char, CharSequence, int, int)
      • decodeHex

        public static <S extends java.io.OutputStream> int decodeHex​(S stream,
                                                                     char separator,
                                                                     java.lang.CharSequence csq,
                                                                     int start,
                                                                     int end)
                                                              throws java.io.IOException
        Type Parameters:
        S - The OutputStream generic type
        Parameters:
        stream - The target OutputStream
        separator - The separator between the HEX values - may be EMPTY_HEX_SEPARATOR
        csq - The CharSequence containing the HEX encoded bytes
        start - Start offset of the HEX sequence (inclusive)
        end - End offset of the HEX sequence (exclusive)
        Returns:
        The number of bytes written to the stream
        Throws:
        java.io.IOException - If failed to write
        java.lang.IllegalArgumentException - If invalid HEX sequence length
        java.lang.NumberFormatException - If invalid HEX characters found
      • fromHex

        public static byte fromHex​(char hi,
                                   char lo)
                            throws java.lang.NumberFormatException
        Throws:
        java.lang.NumberFormatException
      • readInt

        public static int readInt​(java.io.InputStream input,
                                  byte[] buf)
                           throws java.io.IOException
        Read a 32-bit value in network order
        Parameters:
        input - The InputStream
        buf - Work buffer to use
        Returns:
        The read 32-bit value
        Throws:
        java.io.IOException - If failed to read 4 bytes or not enough room in work buffer
        See Also:
        readInt(InputStream, byte[], int, int)
      • readInt

        public static int readInt​(java.io.InputStream input,
                                  byte[] buf,
                                  int offset,
                                  int len)
                           throws java.io.IOException
        Read a 32-bit value in network order
        Parameters:
        input - The InputStream
        buf - Work buffer to use
        offset - Offset in buffer to us
        len - Available length - must have at least 4 bytes available
        Returns:
        The read 32-bit value
        Throws:
        java.io.IOException - If failed to read 4 bytes or not enough room in work buffer
        See Also:
        readUInt(InputStream, byte[], int, int)
      • readUInt

        public static long readUInt​(java.io.InputStream input,
                                    byte[] buf)
                             throws java.io.IOException
        Read a 32-bit value in network order
        Parameters:
        input - The InputStream
        buf - Work buffer to use
        Returns:
        The read 32-bit value
        Throws:
        java.io.IOException - If failed to read 4 bytes or not enough room in work buffer
        See Also:
        readUInt(InputStream, byte[], int, int)
      • readUInt

        public static long readUInt​(java.io.InputStream input,
                                    byte[] buf,
                                    int offset,
                                    int len)
                             throws java.io.IOException
        Read a 32-bit value in network order
        Parameters:
        input - The InputStream
        buf - Work buffer to use
        offset - Offset in buffer to us
        len - Available length - must have at least 4 bytes available
        Returns:
        The read 32-bit value
        Throws:
        java.io.IOException - If failed to read 4 bytes or not enough room in work buffer
        See Also:
        getUInt(byte[], int, int)
      • getUInt

        public static long getUInt​(byte... buf)
        Parameters:
        buf - A buffer holding a 32-bit unsigned integer in big endian format. Note: if more than 4 bytes are available, then only the first 4 bytes in the buffer will be used
        Returns:
        The result as a long whose 32 high-order bits are zero
        See Also:
        getUInt(byte[], int, int)
      • getUInt

        public static long getUInt​(byte[] buf,
                                   int off,
                                   int len)
        Parameters:
        buf - A buffer holding a 32-bit unsigned integer in big endian format.
        off - The offset of the data in the buffer
        len - The available data length. Note: if more than 4 bytes are available, then only the first 4 bytes in the buffer will be used (starting at the specified offset)
        Returns:
        The result as a long whose 32 high-order bits are zero
      • getLong

        public static long getLong​(byte[] buf,
                                   int off,
                                   int len)
      • fromMPIntBytes

        public static java.math.BigInteger fromMPIntBytes​(byte[] mpInt)
      • writeInt

        public static void writeInt​(java.io.OutputStream output,
                                    int value,
                                    byte[] buf)
                             throws java.io.IOException
        Writes a 32-bit value in network order (i.e., MSB 1st)
        Parameters:
        output - The OutputStream to write the value
        value - The 32-bit value
        buf - A work buffer to use - must have enough space to contain 4 bytes
        Throws:
        java.io.IOException - If failed to write the value or work buffer too small
        See Also:
        writeInt(OutputStream, int, byte[], int, int)
      • writeInt

        public static void writeInt​(java.io.OutputStream output,
                                    int value,
                                    byte[] buf,
                                    int off,
                                    int len)
                             throws java.io.IOException
        Writes a 32-bit value in network order (i.e., MSB 1st)
        Parameters:
        output - The OutputStream to write the value
        value - The 32-bit value
        buf - A work buffer to use - must have enough space to contain 4 bytes
        off - The offset to write the value
        len - The available space
        Throws:
        java.io.IOException - If failed to write the value or work buffer too small
        See Also:
        writeUInt(OutputStream, long, byte[], int, int)
      • writeUInt

        public static void writeUInt​(java.io.OutputStream output,
                                     long value,
                                     byte[] buf)
                              throws java.io.IOException
        Writes a 32-bit value in network order (i.e., MSB 1st)
        Parameters:
        output - The OutputStream to write the value
        value - The 32-bit value
        buf - A work buffer to use - must have enough space to contain 4 bytes
        Throws:
        java.io.IOException - If failed to write the value or work buffer too small
        See Also:
        writeUInt(OutputStream, long, byte[], int, int)
      • writeUInt

        public static void writeUInt​(java.io.OutputStream output,
                                     long value,
                                     byte[] buf,
                                     int off,
                                     int len)
                              throws java.io.IOException
        Writes a 32-bit value in network order (i.e., MSB 1st)
        Parameters:
        output - The OutputStream to write the value
        value - The 32-bit value
        buf - A work buffer to use - must have enough space to contain 4 bytes
        off - The offset to write the value
        len - The available space
        Throws:
        java.io.IOException - If failed to write the value or work buffer to small
        See Also:
        putUInt(long, byte[], int, int)
      • putUInt

        public static int putUInt​(long value,
                                  byte[] buf)
        Writes a 32-bit value in network order (i.e., MSB 1st)
        Parameters:
        value - The 32-bit value
        buf - The buffer
        Returns:
        The number of bytes used in the buffer
        Throws:
        java.lang.IllegalArgumentException - if not enough space available
        See Also:
        putUInt(long, byte[], int, int)
      • putUInt

        public static int putUInt​(long value,
                                  byte[] buf,
                                  int off,
                                  int len)
        Writes a 32-bit value in network order (i.e., MSB 1st)
        Parameters:
        value - The 32-bit value
        buf - The buffer
        off - The offset to write the value
        len - The available space
        Returns:
        The number of bytes used in the buffer
        Throws:
        java.lang.IllegalArgumentException - if not enough space available
      • putLong

        public static int putLong​(long value,
                                  byte[] buf,
                                  int off,
                                  int len)
      • equals

        public static boolean equals​(byte[] a1,
                                     byte[] a2)
        Compares the contents of 2 arrays of bytes - Note: do not use it to execute security related comparisons (e.g. MACs) since the method leaks timing information. Use Mac#equals method instead.
        Parameters:
        a1 - 1st array
        a2 - 2nd array
        Returns:
        true if all bytes in the compared arrays are equal
      • equals

        public static boolean equals​(byte[] a1,
                                     int a1Offset,
                                     byte[] a2,
                                     int a2Offset,
                                     int length)
        Compares the contents of 2 arrays of bytes - Note: do not use it to execute security related comparisons (e.g. MACs) since the method leaks timing information. Use Mac#equals method instead.
        Parameters:
        a1 - 1st array
        a1Offset - Offset to start comparing in 1st array
        a2 - 2nd array
        a2Offset - Offset to start comparing in 2nd array
        length - Number of bytes to compare
        Returns:
        true if all bytes in the compared arrays are equal when compared from the specified offsets and up to specified length
      • getNextPowerOf2

        public static int getNextPowerOf2​(int value)
      • updateLengthPlaceholder

        public static int updateLengthPlaceholder​(Buffer buffer,
                                                  int lenPos)
        Used for encodings where we don't know the data length before adding it to the buffer. The idea is to place a 32-bit "placeholder", encode the data and then return back to the placeholder and update the length. The method calculates the encoded data length, moves the write position to the specified placeholder position, updates the length value and then moves the write position it back to its original value.
        Parameters:
        buffer - The Buffer
        lenPos - The offset in the buffer where the length placeholder is to be update - Note: assumption is that the encoded data starts immediately after the placeholder
        Returns:
        The amount of data that has been encoded
      • updateLengthPlaceholder

        public static void updateLengthPlaceholder​(Buffer buffer,
                                                   int lenPos,
                                                   long dataLength)
        Updates a 32-bit "placeholder" location for data length - moves the write position to the specified placeholder position, updates the length value and then moves the write position it back to its original value.
        Parameters:
        buffer - The Buffer
        lenPos - The offset in the buffer where the length placeholder is to be update - Note: assumption is that the encoded data starts immediately after the placeholder
        dataLength - The length to update - a UINT32 value as a long
      • clear

        public static <B extends Buffer> B clear​(B buffer)
        Type Parameters:
        B - The generic buffer type
        Parameters:
        buffer - A Buffer instance - ignored if null
        Returns:
        The same as the input instance
      • validateInt32Value

        public static long validateInt32Value​(long value,
                                              java.lang.String message)
      • validateInt32Value

        public static long validateInt32Value​(long value,
                                              java.lang.String format,
                                              java.lang.Object arg)
      • validateInt32Value

        public static long validateInt32Value​(long value,
                                              java.lang.String format,
                                              java.lang.Object... args)
      • isValidInt32Value

        public static boolean isValidInt32Value​(long value)
      • validateUint32Value

        public static long validateUint32Value​(long value,
                                               java.lang.String message)
      • validateUint32Value

        public static long validateUint32Value​(long value,
                                               java.lang.String format,
                                               java.lang.Object arg)
      • validateUint32Value

        public static long validateUint32Value​(long value,
                                               java.lang.String format,
                                               java.lang.Object... args)
      • isValidUint32Value

        public static boolean isValidUint32Value​(long value)