Class UuidUtil
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 Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic UUIDbinary2Uuid(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.static UUIDbinary2Uuid(byte[] bytes, ByteOrder byteOrder) Parses a UUID from 16 bytes using the requested byte order for each 64-bit half.static StringcompactUuid(String uuid) Removes hyphen characters from a canonical UUID string.static StringcompactUuid(UUID uuid) Returns the UUID string without hyphen separators.static UUIDconvert2Uuid(byte[] bytes) Parses a UUID from a byte array in one of several encodings.static UUIDconvert2Uuid(Object uuidObj) Converts a supported value toUUIDby runtime type.static UUIDconvert2Uuid(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.static UUIDconvert2Uuid(UUID uuid) Pass-through for an existingUUID.static UUIDReconstructs aUUIDfrom the unsigned 128-bit layout produced byconvertToBigInteger(UUID).static BigIntegerMaps a UUID to an unsigned 128-bit integer asBigInteger: high 64 bits in the high half, low 64 bits in the low half, each half interpreted unsigned before combination.static StringexpandUuid(String compUuid) Inserts hyphens into a 32-character compact hex string, producing the canonical UUID text form.static UUIDhex2Uuid(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.static UUIDParses a UUID from a 32-character hex string (no hyphens), building the canonical form in acharbuffer and parsing withUUID.fromString(String).static booleanisUuid(byte[] uuid) Returns whetheruuidis 32–36 ASCII bytes accepted byhex2Uuid(byte[]).static booleanReturns whetheruuidis accepted byconvert2Uuid(String).static UUIDmicrosoftGuidBinary2Uuid(byte[] bytes) Parses a UUID from Microsoft GUID binary layout.static byte[]uuid2binary(UUID uuid) Encodes a UUID as 16 bytes: most significant bits first, then least significant bits, eachlongin big-endian order (same layout asByteBufferputLong).static byte[]uuid2binary(UUID uuid, ByteOrder byteOrder) Encodes a UUID as 16 bytes using the requested byte order for each 64-bit half.static byte[]uuid2MicrosoftGuidBinary(UUID uuid) Encodes a UUID using Microsoft GUID binary layout.
-
Constructor Details
-
UuidUtil
public UuidUtil()
-
-
Method Details
-
compactUuid
Returns the UUID string without hyphen separators.Example:
550e8400-e29b-41d4-a716-446655440000->550e8400e29b41d4a716446655440000.- Parameters:
uuid- the UUID; must not benull- Returns:
- 32 lowercase hex characters, most significant bits first
-
compactUuid
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 benull- Returns:
- the same characters without
'-'
-
expandUuid
Inserts hyphens into a 32-character compact hex string, producing the canonical UUID text form.If
compUuidis not exactly 32 characters long, it is returned unchanged (includingnull).- Parameters:
compUuid- 32 hex digits without hyphens, or any other string- Returns:
- canonical 8-4-4-4-12 string, or
compUuidwhen length is not 32
-
convert2Uuid
Converts a supported value toUUIDby runtime type.Delegates to
convert2Uuid(UUID),convert2Uuid(byte[]), orconvert2Uuid(String).BigIntegervalues are interpreted viaconvertFromBigInteger(BigInteger). Any other type causesIllegalArgumentException.- Parameters:
uuidObj-null,UUID,byte[],String, orBigInteger- Returns:
- parsed UUID, or
nullwhenuuidObjisnull - Throws:
IllegalArgumentException- ifuuidObjis neithernullnor a supported type
-
convert2Uuid
Pass-through for an existingUUID.- Parameters:
uuid- the UUID, ornull- Returns:
uuid
-
convert2Uuid
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 ashex2Uuid(byte[]))
- Parameters:
bytes-null, empty, 16 bytes, or 32–36 ASCII UUID bytes- Returns:
- the UUID, or
nullfornullor empty array - Throws:
IllegalArgumentException- if length is not 0, 16, or 32–36
- length
-
convert2Uuid
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
nullfornullor blank normalized string - Throws:
IllegalArgumentException- if the normalized string cannot be interpreted as a UUID
-
hex2Uuid
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, ornull- Returns:
- the UUID, or
nullifhexBytesisnull - Throws:
IllegalArgumentException- if length is less than 32 or greater than 36, or the bytes are not a UUID
-
hex2Uuid
Parses a UUID from a 32-character hex string (no hyphens), building the canonical form in acharbuffer and parsing withUUID.fromString(String).- Parameters:
hexString- exactly 32 hex digits, ornull- Returns:
- the UUID, or
nullifhexStringisnull - Throws:
IllegalArgumentException- if length is not 32
-
uuid2binary
Encodes a UUID as 16 bytes: most significant bits first, then least significant bits, eachlongin big-endian order (same layout asByteBufferputLong).- Parameters:
uuid- the UUID, ornull- Returns:
- a new 16-byte array, or
nullifuuidisnull
-
uuid2binary
Encodes a UUID as 16 bytes using the requested byte order for each 64-bit half.- Parameters:
uuid- the UUID, ornullbyteOrder- byte order for the most/least significantlonghalves; must not benull- Returns:
- a new 16-byte array, or
nullifuuidisnull
-
binary2Uuid
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), ornull- Returns:
- the UUID, or
nullifbytesisnull - Throws:
BufferUnderflowException- if fewer than 16 bytes are available
-
binary2Uuid
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; useByteOrder.LITTLE_ENDIANonly when the source explicitly stores the two 64-bit halves that way.- Parameters:
bytes- at least 16 bytes (only the first 16 are read), ornullbyteOrder- byte order for the most/least significantlonghalves; must not benull- Returns:
- the UUID, or
nullifbytesisnull - Throws:
BufferUnderflowException- if fewer than 16 bytes are available
-
uuid2MicrosoftGuidBinary
Encodes a UUID using Microsoft GUID binary layout.Unlike
ByteOrder.LITTLE_ENDIANfor twolonghalves, GUID binary layout stores the first three UUID fields (4-2-2bytes) little-endian and keeps the remaining 8 bytes unchanged.- Parameters:
uuid- the UUID, ornull- Returns:
- a new 16-byte array in Microsoft GUID binary layout, or
nullifuuidisnull
-
microsoftGuidBinary2Uuid
Parses a UUID from Microsoft GUID binary layout.The first three UUID fields (
4-2-2bytes) 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), ornull- Returns:
- the UUID, or
nullifbytesisnull - Throws:
BufferUnderflowException- if fewer than 16 bytes are available
-
isUuid
Returns whetheruuidis accepted byconvert2Uuid(String).null, blank input, and strings that cannot be parsed returnfalsewithout throwing.- Parameters:
uuid- the string to test, ornull- Returns:
trueifconvert2Uuid(String)would return a UUID
-
isUuid
public static boolean isUuid(byte[] uuid) Returns whetheruuidis 32–36 ASCII bytes accepted byhex2Uuid(byte[]).nulland any other length returnfalsewithout throwing.- Parameters:
uuid- the bytes to test, ornull- Returns:
trueifhex2Uuid(byte[])would return a UUID
-
convertToBigInteger
Maps a UUID to an unsigned 128-bit integer asBigInteger: high 64 bits in the high half, low 64 bits in the low half, each half interpreted unsigned before combination.- Parameters:
id- the UUID, ornull- Returns:
lo + hi * 2^64with unsigned halves, ornullifidisnull
-
convertFromBigInteger
Reconstructs aUUIDfrom the unsigned 128-bit layout produced byconvertToBigInteger(UUID).- Parameters:
x- the big integer, ornull- Returns:
- the UUID, or
nullifxisnull - Throws:
ArithmeticException- if a half does not fit in a signedlongafter adjustment
-