Class UuidUtil

java.lang.Object
io.github.connellite.util.UuidUtil

public class UuidUtil extends Object
Utilities for UUID: canonical and compact string form, 16-byte binary layout, 32-character hex, conversion from arbitrary Object shapes, and unsigned 128-bit BigInteger mapping.
  • Constructor Details

    • UuidUtil

      public UuidUtil()
  • Method Details

    • compactUuid

      public static String compactUuid(UUID uuid)
      Returns the UUID string without hyphen separators.

      Example: 550e8400-e29b-41d4-a716-446655440000 -> 550e8400e29b41d4a716446655440000.

      Parameters:
      uuid - the UUID; must not be null
      Returns:
      32 lowercase hex characters, most significant bits first
    • compactUuid

      public static String compactUuid(String uuid)
      Removes hyphen characters from a canonical UUID string.

      Example: 550e8400-e29b-41d4-a716-446655440000 -> 550e8400e29b41d4a716446655440000.

      Parameters:
      uuid - the string, typically 36 characters with hyphens; must not be null
      Returns:
      the same characters without '-'
    • expandUuid

      public static String expandUuid(String compUuid)
      Inserts hyphens into a 32-character compact hex string, producing the canonical UUID text form.

      If compUuid is not exactly 32 characters long, it is returned unchanged (including null).

      Parameters:
      compUuid - 32 hex digits without hyphens, or any other string
      Returns:
      canonical 8-4-4-4-12 string, or compUuid when length is not 32
    • convert2Uuid

      public static UUID convert2Uuid(Object uuidObj)
      Converts a supported value to UUID by runtime type.

      Delegates to convert2Uuid(UUID), convert2Uuid(byte[]), or convert2Uuid(String). BigInteger values are interpreted via convertFromBigInteger(BigInteger). Any other type causes IllegalArgumentException.

      Parameters:
      uuidObj - null, UUID, byte[], String, or BigInteger
      Returns:
      parsed UUID, or null when uuidObj is null
      Throws:
      IllegalArgumentException - if uuidObj is neither null nor a supported type
    • convert2Uuid

      public static UUID convert2Uuid(UUID uuid)
      Pass-through for an existing UUID.
      Parameters:
      uuid - the UUID, or null
      Returns:
      uuid
    • convert2Uuid

      public static UUID convert2Uuid(byte[] bytes)
      Parses a UUID from a byte array in one of several encodings.
      • length 0: null
      • length 16: RFC binary (MSB then LSB, big-endian)
      • length 32–36: ASCII hex digits with optional hyphens (same as hex2Uuid(byte[]))
      Parameters:
      bytes - null, empty, 16 bytes, or 32–36 ASCII UUID bytes
      Returns:
      the UUID, or null for null or empty array
      Throws:
      IllegalArgumentException - if length is not 0, 16, or 32–36
    • convert2Uuid

      public static UUID convert2Uuid(String uuidString)
      Parses a UUID from a string: trims, skips optional leading/trailing brace or square bracket characters independently, and parses 16 bytes using PostgreSQL-compatible hyphen placement.

      Blank input after normalization yields null.

      Parameters:
      uuidString - null, blank, compact/canonical string, brace/square-bracket wrapped form, or variants with hyphens after groups of 4 hexadecimal digits
      Returns:
      the UUID, or null for null or blank normalized string
      Throws:
      IllegalArgumentException - if the normalized string cannot be interpreted as a UUID
    • hex2Uuid

      public static UUID hex2Uuid(byte[] hexBytes)
      Parses a UUID from 32–36 bytes that are ASCII hex digits (0-9, a-f, A-F) with optional PostgreSQL-compatible hyphen placement.
      Parameters:
      hexBytes - 32–36 ASCII UUID bytes, or null
      Returns:
      the UUID, or null if hexBytes is null
      Throws:
      IllegalArgumentException - if length is less than 32 or greater than 36, or the bytes are not a UUID
    • hex2Uuid

      public static UUID hex2Uuid(String hexString)
      Parses a UUID from a 32-character hex string (no hyphens), building the canonical form in a char buffer and parsing with UUID.fromString(String).
      Parameters:
      hexString - exactly 32 hex digits, or null
      Returns:
      the UUID, or null if hexString is null
      Throws:
      IllegalArgumentException - if length is not 32
    • uuid2binary

      public static byte[] uuid2binary(UUID uuid)
      Encodes a UUID as 16 bytes: most significant bits first, then least significant bits, each long in big-endian order (same layout as ByteBuffer putLong).
      Parameters:
      uuid - the UUID, or null
      Returns:
      a new 16-byte array, or null if uuid is null
    • uuid2binary

      public static byte[] uuid2binary(UUID uuid, ByteOrder byteOrder)
      Encodes a UUID as 16 bytes using the requested byte order for each 64-bit half.
      Parameters:
      uuid - the UUID, or null
      byteOrder - byte order for the most/least significant long halves; must not be null
      Returns:
      a new 16-byte array, or null if uuid is null
    • binary2Uuid

      public static UUID binary2Uuid(byte[] bytes)
      Parses a UUID from 16 bytes: first 8 bytes are the most significant bits, last 8 the least significant bits, both big-endian.
      Parameters:
      bytes - at least 16 bytes (only the first 16 are read), or null
      Returns:
      the UUID, or null if bytes is null
      Throws:
      BufferUnderflowException - if fewer than 16 bytes are available
    • binary2Uuid

      public static UUID binary2Uuid(byte[] bytes, ByteOrder byteOrder)
      Parses a UUID from 16 bytes using the requested byte order for each 64-bit half.

      The default UUID/RFC/PostgreSQL binary representation is ByteOrder.BIG_ENDIAN; use ByteOrder.LITTLE_ENDIAN only when the source explicitly stores the two 64-bit halves that way.

      Parameters:
      bytes - at least 16 bytes (only the first 16 are read), or null
      byteOrder - byte order for the most/least significant long halves; must not be null
      Returns:
      the UUID, or null if bytes is null
      Throws:
      BufferUnderflowException - if fewer than 16 bytes are available
    • uuid2MicrosoftGuidBinary

      public static byte[] uuid2MicrosoftGuidBinary(UUID uuid)
      Encodes a UUID using Microsoft GUID binary layout.

      Unlike ByteOrder.LITTLE_ENDIAN for two long halves, GUID binary layout stores the first three UUID fields (4-2-2 bytes) little-endian and keeps the remaining 8 bytes unchanged.

      Parameters:
      uuid - the UUID, or null
      Returns:
      a new 16-byte array in Microsoft GUID binary layout, or null if uuid is null
    • microsoftGuidBinary2Uuid

      public static UUID microsoftGuidBinary2Uuid(byte[] bytes)
      Parses a UUID from Microsoft GUID binary layout.

      The first three UUID fields (4-2-2 bytes) are read little-endian; the remaining 8 bytes are read in their stored order.

      Parameters:
      bytes - at least 16 bytes (only the first 16 are read), or null
      Returns:
      the UUID, or null if bytes is null
      Throws:
      BufferUnderflowException - if fewer than 16 bytes are available
    • isUuid

      public static boolean isUuid(String uuid)
      Returns whether uuid is accepted by convert2Uuid(String). null, blank input, and strings that cannot be parsed return false without throwing.
      Parameters:
      uuid - the string to test, or null
      Returns:
      true if convert2Uuid(String) would return a UUID
    • isUuid

      public static boolean isUuid(byte[] uuid)
      Returns whether uuid is 32–36 ASCII bytes accepted by hex2Uuid(byte[]). null and any other length return false without throwing.
      Parameters:
      uuid - the bytes to test, or null
      Returns:
      true if hex2Uuid(byte[]) would return a UUID
    • convertToBigInteger

      public static BigInteger convertToBigInteger(UUID id)
      Maps a UUID to an unsigned 128-bit integer as BigInteger: high 64 bits in the high half, low 64 bits in the low half, each half interpreted unsigned before combination.
      Parameters:
      id - the UUID, or null
      Returns:
      lo + hi * 2^64 with unsigned halves, or null if id is null
    • convertFromBigInteger

      public static UUID convertFromBigInteger(BigInteger x)
      Reconstructs a UUID from the unsigned 128-bit layout produced by convertToBigInteger(UUID).
      Parameters:
      x - the big integer, or null
      Returns:
      the UUID, or null if x is null
      Throws:
      ArithmeticException - if a half does not fit in a signed long after adjustment