Class UuidParser

java.lang.Object
cloud.opencode.base.id.uuid.UuidParser
All Implemented Interfaces:
IdParser<UUID, UuidParser.ParsedUuid>
public final class UuidParser extends Object implements IdParser<UUID, UuidParser.ParsedUuid>
UUID Parser - Extracts structured information from UUID objects UUID解析器 - 从UUID对象中提取结构化信息

Implements IdParser for UUID, supporting version detection, timestamp extraction (for time-based UUIDs v1, v6, v7), and validation. Fills the gap where other ID types have parsers but UUID did not.

为UUID实现IdParser，支持版本检测、时间戳提取 （适用于基于时间的UUID v1、v6、v7）和验证。 填补了其他ID类型有解析器而UUID没有的空缺。

Features | 主要功能:

  • Detect UUID version (1-8) - 检测UUID版本（1-8）
  • Extract timestamp for v1, v6, v7 UUIDs - 提取v1、v6、v7 UUID的时间戳
  • Variant detection - 变体检测
  • Short string representation (no hyphens) - 短字符串表示（无连字符）

Usage Examples | 使用示例:

UuidParser parser = UuidParser.create();

// Parse a UUID v7
UUID v7 = UuidV7Generator.create().generate();
UuidParser.ParsedUuid parsed = parser.parse(v7);
System.out.println("Version: " + parsed.version());        // 7
System.out.println("Timestamp: " + parsed.timestamp());    // Instant
System.out.println("Time-ordered: " + parsed.timeOrdered()); // true
System.out.println("Short: " + parsed.toShortString());    // 32-char string

// Extract timestamp directly
Instant ts = parser.extractTimestamp(v7);

// Validate
boolean valid = parser.isValid(v7); // true

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是（无状态）
  • Null-safe: No (throws on null) - 空值安全: 否（空值抛异常）
Since:
JDK 25, opencode-base-id V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    UuidParser.ParsedUuid
    Structured result of parsing a UUID UUID解析的结构化结果

  • Method Summary

    Modifier and Type
    Method
    Description
    static UuidParser
    create()
    Returns the singleton UuidParser instance 返回单例UuidParser实例
    Instant
    extractTimestamp(UUID uuid)
    Extracts the embedded timestamp from a time-based UUID (v1, v6, v7) 从基于时间的UUID（v1、v6、v7）中提取嵌入的时间戳
    boolean
    isValid(UUID uuid)
    Validates that the UUID is non-null and has a recognized version 验证UUID非空且具有可识别的版本
    UuidParser.ParsedUuid
    parse(UUID uuid)
    Parses a UUID into a structured result 将UUID解析为结构化结果

    Methods inherited from class Object

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

  • Method Details

    • create

      public static UuidParser create()
      Returns the singleton UuidParser instance 返回单例UuidParser实例
      Returns:
      parser | 解析器

    • parse

      public UuidParser.ParsedUuid parse(UUID uuid)
      Parses a UUID into a structured result 将UUID解析为结构化结果

      Examples | 示例:

      parse(UuidV7Generator.create().generate()) → ParsedUuid{version=7, timeOrdered=true, timestamp=...}
parse(UUID.randomUUID())                   → ParsedUuid{version=4, timeOrdered=false, timestamp=null}

      Performance | 性能:

      Time: O(1), Space: O(1)

      Specified by:
      parse in interface IdParser<UUID, UuidParser.ParsedUuid>
      Parameters:
      uuid - the UUID to parse | 要解析的UUID
      Returns:
      parsed result | 解析结果
      Throws:
      OpenIdGenerationException - if uuid is null | uuid为null时抛出

    • extractTimestamp

      public Instant extractTimestamp(UUID uuid)
      Extracts the embedded timestamp from a time-based UUID (v1, v6, v7) 从基于时间的UUID（v1、v6、v7）中提取嵌入的时间戳

      Examples | 示例:

      extractTimestamp(v7Uuid) = Instant (ms precision)
extractTimestamp(v4Uuid) = throws OpenIdGenerationException

      Performance | 性能:

      Time: O(1), Space: O(1)

      Specified by:
      extractTimestamp in interface IdParser<UUID, UuidParser.ParsedUuid>
      Parameters:
      uuid - the UUID | UUID
      Returns:
      the embedded timestamp | 嵌入的时间戳
      Throws:
      OpenIdGenerationException - if the UUID is not time-based (not v1/v6/v7) | 非基于时间的UUID时抛出

    • isValid

      public boolean isValid(UUID uuid)
      Validates that the UUID is non-null and has a recognized version 验证UUID非空且具有可识别的版本
      Specified by:
      isValid in interface IdParser<UUID, UuidParser.ParsedUuid>
      Parameters:
      uuid - the UUID | UUID
      Returns:
      true if valid | 如果有效返回true